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Dynamic Screen Manager APIs 


The Dynamic Screen Manager (DSM) APIs are a set of screen I/O interfaces that provide a dynamic way to 
create and manage screens for the Integrated Language Environment (ILE) high-level languages. Because 
the DSM interfaces are bindable, they are accessible to ILE programs only. 


The DSM APIs provide an alternative to the existing way of defining screen appearance outside a program 
by coding in DDS or UIM, for example. Instead, programmers can use a series of calls to DSM within their 
programs to dynamically specify and control screen appearance for their applications. Unlike static 
definition methods, the DSM interfaces provide the flexibility needed for those applications requiring more 
dynamic screen control. The DSM support provided varies from low-level interfaces for direct screen 
manipulation to windowing support. 


The DSM APIs fall into the following functional groups: 


e Low-level services provide a direct interface to the 5250 data stream commands. These APIs are 


used to query and manipulate the state of the screen; to create, query, and manipulate input and 
command buffers used to interact with the screen; and to define fields and write data to the screen. 


e Window services are used to create, delete, move, and resize windows, and to manage multiple 
windows during a session. 


e Session services provide a general scrolling interface that can be used to create, query, and 
manipulate sessions, and to perform input and output operations to sessions. 


See Using Dynamic Screen Manager APIs for additional information. 


See Code disclaimer information for information pertaining to code examples. 
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Using Dynamic Screen Manager APIs 


Data Structures for DSM APlis 


Data structures for use with ILE C, ILE COBOL, and ILE RPG/400®) are available in the QSYSINC 
library in member QSNAPI for service program QSNAPI. 


Omitting Parameters with Associated Lengths 


To omit a parameter with an associated length parameter, that length parameter should be omitted or 
specified as 0. If the length parameter is specified with a value greater than 0, the parameter with which it is 
associated is required. 


For example, to omit the user extension information on the low-level environment, specify either a NULL 
pointer by value, or 0 by reference for the length. The extension information structure is ignored. If the 
length is greater than 0, the extension information structure cannot be NULL. If it is, then a Required 
parameter omitted error is generated. 
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Low-Level Screen I/O Services APIs 


The low-level services are divided into the following functional groups: 


e Screen Manipulation and Query APIs, which are used to query and manipulate the state of the 
screen. 


e Buffer Manipulation and Query APIs, which are used to create, query, and manipulate input and 
command buffers used to interact with the screen. 


e Screen Input APIs, which are used to read field data and other information from the screen. 


e Screen Output APIs, which are used to define fields and write data and other information to the 
screen. 


The low-level screen I/O services APIs provide a direct interface to the 5250 data stream commands and 
user-defined data streams for performing basic screen I/O operations. For detailed information about the 
results and interactions of these operations, refer to the following 5250 data stream documentation: 


e@ 5250 Functions Reference, SA21-9247-06. This book is not accessible online, but can be ordered 
from the IBM Publications Center. 


e 5494 Remote Control Unit Functions Reference R3.1, SC30-3533-04. This book can be viewed 
online through the IBM Publications Center. 


For additional information, select one of the following: 


e Low-Level Services Examples 


e DSM Error Handling 
e Device Support 


e Operating Environments 


e Direct and Indirect Operations 


e DBCS Considerations 


e Performance Considerations 


e Limitations and Restrictions 


e@ 5250 Data Stream Details, including 


o AID-Generating Keys 


Control Characters 


Screen Attribute Characters 
Display Address 
Insert Cursor Address 


Modified Data Tag (MDT) Bit 


Resequencing 
States and Modes 


O O09 O° O° Oo QO. © 


Dumping the 5250 Data Stream Commands 
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Using Low-Level Screen I/O Services APIs 


DSM Error Handling 


Calls to most of the interfaces can result in a direct I/O operation, or in the storing of commands in a 
command buffer. The command buffer provides a way of saving the commands so that multiple operations 
can be specified and performed in a single I/O operation. DSM performs error handling as much as possible 
prior to issuing an I/O operation. For example, if a request is made to place the screen in wide mode, and 
the display does not support this mode, DSM detects and reports the error condition before performing an 
I/O operation. This way of handling errors is particularly useful in the case where multiple commands have 
been saved in a buffer. Otherwise, there is no obvious way to determine which command was in error when 
the I/O operation fails. 


The errors that can occur for each operation are listed with the operation. If an error message indicates that 
the error is issued for a negative response code, this means that the error was not detected by DSM and 
occurred on the I/O operation. 


Note: When you are using the OS/400 TELNET display station emulation, an unsuccessful I/O operation 
may be undetected initially, but will be reported on the next operation. 


Device Support 


The 5250 Query command is used to determine the valid commands for a particular device. This command 
is issued for the current device at the start of each DSM session and the information is saved for subsequent 
queries. If the 5250 Query command is not supported, the base data stream support as documented in the 
5250 Functions Reference is assumed, with color and wide support being determined by the device type. 


Operating Environments 


The low-level interfaces operate within an environment that can be defined using the Create Low-Level 
Environment (QsnCrtEnv) API. The low-level environment defines the operating modes, such as DBCS 
support and the window mode. The environment is passed as a parameter to most of the low-level services 
APIs. There is no need to define a low-level environment unless you need a specific operating environment 
that is different from the default. The default low-level environment is indicated on the low-level service 
APIs by specifying the environment handle as zero. 


Direct and Indirect Operations 


Many of the low-level APIs accept an optional command buffer as a parameter. For such APIs, the 
command buffer can be used to store and accumulate a group of requested operations. The accumulated 
operations can then be written to the screen in a single I/O operation. Better performance can be achieved 
because a group of repetitive operations can be issued to the screen without having to recall the sequence of 
individual APIs for each repeated operation. 


A direct operation is one that omits the command buffer. The requested operation takes place 
immediately. For most APIs, specifying the command buffer results in an indirect operation. No I/O 
operation takes place and the operation is simply stored in the command buffer. Several of the screen input 
APIs, however, do perform a direct operation when the command buffer is specified. This semantic is 


discussed in Read Input Fields (QsnReadInp) API. 


DBCS Considerations 


You can write DBCS data enclosed with SO/SI to the screen, and when the underlying display supports it, 
graphic DBCS using the Write Data (QsnWrtDta) API to specify the data stream Write Extended Attribute 
order. (See the 5250 data stream documentation for further details.) You can define fields as being DBCS 
through the Set Field (QsnSetFld) API using the appropriate field control word. DBCS data can be written 
to such fields as described above. If you specify DBCS support on the low-level environment description, 
(see Format of the Low-Level Environment Description), the APIs will handle the parsing of DBCS data 


and fields appropriately. 


The APIs do not provide any special processing of DBCS data, such as adding SO/SI to DBCS graphic data 
when graphic data is not supported by the display. For example, if you want to define a field as graphic 
DBCS and write graphic DBCS data to it, code the QsnSetFld API specifying a control word of 
QSN_FCS_DBCS_PURE (x'8220") and then write the graphic data to a command buffer using the 
QsnWrtDta API. Precede and follow this data with Write Extended Attribute orders to add the extended 
NLS SO/SI attributes. If you want to write a graphic data value to a non-graphic DBCS field, you must 
enclose the graphic DBCS data with SO/SI prior to calling the QsnWrtDta API. 


*Performance Considerations 


The following operations can incur overhead and adversely affect the performance of your application: 
e QsnCrtEnv 


Specifying translation of x'3f to x'lf' can incur overhead because all outgoing data must be checked 
for this value. This option should be specified only if CDRA is on and translation between the code 
pages will result in a x'3f' occurrence in data to be displayed. 


e QsnSavScr 


This operation results in the entire contents of the screen being read, which can adversely affect 
response time. This is typically about 3KB, but could be up to 28KB. 


e QsnRstScr 
This operation writes the result of a save screen back to the device, which can adversely affect 
response time. 


If you have GUI support, you can put additional commands after the QsnSavScr or QsnRstScr APIs to 
reduce I/O operations and improve performance. 


Deleting structures associated with handles, such as command buffers, prior to exiting a program will 
improve performance for the programs that use APIs that create handles.*& 


*Limitations and Restrictions 


The following limitations or restrictions apply to the low-level interfaces: 


e Certain functions are supported by control units that do not support the 5250 Query command. If 
the Query command is not supported, it is assumed that the particular function is not supported 
either. These functions are transparent data support and move cursor order support. Device 
attributes such as wide mode and color support are determined based on the device type if the 5250 
Query command is not supported. 


e For the Retrieve Display Mode (QsnRtvMod) operation to correctly report the current state of the 
display, all commands that affect this state (such as a Clear Unit or Clear Unit Alternate) must 
occur as the first command in any command stream written to the display. This is because the work 
station control unit inspects the first command in the stream to determine if a state change is taking 
place. Most iSeries programs, including the DSM APIs, send these commands only at the 
beginning of a stream. If you write a stream in which such commands do not appear at the 
beginning of the stream, the results of the Retrieve Display Mode (QsnRtvMod) operation may not 
be accurate. 


e@ When conversions are performed, they are performed only after a Read Input Fields (QsnReadInp), 
Read Modified Fields (QsnReadMDT), Read Modified Alternate (QsnReadMDTAIt), Read 
Immediate (QsnReadImm), or Read Modified Immediate Alternate (QsnReadMDTImmAIt) 
operation. They are performed on all incoming field data, including transparent and numeric data. 
You must turn conversion on and off. To prevent certain data from being converted, you explicitly 
set the conversion options on the QsnCrtEnv and QsnChgEnv APIs. The conversions that are 
affected by this are CDRA conversion based on the job CCSID and conversions of X'1F' in the 
incoming data stream to X'3F'.“& 
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Screen Manipulation and Query APIs 


The screen manipulation and query APIs are used to query and manipulate the state of the screen. They are: 


Change Low-Level Environment (QsnChgEnv) changes the low-level environment description. 


Clear Field Table (QsnClrFldTbl) clears the format table but does not alter the display. 


Clear Screen (QsnClrScr) clears the screen and sets the screen size. 


Create Low-Level Environment (QsnCrtEnv) creates the environment for the low-level services 
APIs. 

Delete Low-Level Environment (QsnDItEnv) deletes the environment for the low-level services 
APIs. 

Initialize Low-Level Environment Description (QsnInzEnvD) initializes the low-level environment 
description. 


Query 5250 (QsnQry5250) returns the results of the 5250 Query command. 


Query Color Support (QsnQryColorSup) determines if the display device supports color. 


Query Display Mode Support (QsnQryModSup) queries if the display device allows a given mode. 


Restore Screen (QsnRstScr) restores the contents of a screen saved with Save Screen (QsnSavScr) 
API. 


Retrieve Display Mode (QsnRtvMod) queries the current device mode. 


Retrieve Low-Level Environment Description (QsnRtvEnvD) retrieves the low-level environment 
description. 


Retrieve Low-Level Environment User Data (QsnRtvEnvDta) returns a pointer to the user data for 
the low-level environment. 


Retrieve Low-Level Environment Window Mode (QsnRtvEnvWinMod) retrieves the low-level 
interface environment window mode description. 


Retrieve Screen Dimensions (QsnRtvScrDim) retrieves the screen dimensions. 


Roll Down (QsnRollDown) rolls the screen down by the given number of rows. 
Roll Up (QsnRollUp) rolls the screen up by the given number of rows. 
Save Screen (QsnSavScr) saves the present display so it can be restored later. 


Set Low-Level Environment Window Mode (QsnSetEnvWinMod) sets the window mode for the 
low-level interface environment. 
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Change Low-Level Environment (QsnChgEnv) 
API 


Required Parameter Group: 


1 Low-level environment description Char(*) 


2 Length of low-level environment Binary(4) 
description 


Omissible Parameter Group: 


3 Low-level environment handle Binary(4) 
4 Error Code Char(**) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Change Low-Level Environment (QsnChgEnv) API changes the description for the given low-level 
environment. The Change Low-Level Environment exit routine will be called if specified on the user 
extension information of the Create Low-Level Environment (QsnCrtEnv) API. 


Authorities and Locks 


Display file authority 
*USE 

Display file library authority 
*USE 

Exit routine authority 
*EXECUTE 


Required Parameter Group 


Low-level environment description 
INPUT; CHAR(*) 


The new environment description for the given environment. The format of this parameter is shown 
in Format of the Low-Level Environment Description. 


Length of low-level environment description 
INPUT; Binary(4) 


The length of the low-level environment description parameter. The value specified must be 16, 36 
or 38. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment to be modified. If this parameter is omitted or specified as 0, the default 
low-level environment is used. 
Error code 
V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 


CPFA318 E Error calling exit routine. 


CPFA31E E 
CPFA327 E 
CPFA334 E 
CPFA344 E 


API Introduced: V2R3 


Required parameter &1 omitted. 
Low level environment description value incorrect. 
Low level environment handle incorrect. 


The file &2 in library &3 is not valid. 
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Clear Field Table (QsnClIrFidTbl) API 


Omissible Parameter Group: 


Command buffer handle Binary(4) 
Low-level environment handle Binary(4) 
Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Clear Field Table (QsnClrFldTbl) API erases the contents of the format table without affecting the 
display station screen. This allows for example, all input field definitions to be erased from the screen 
without altering the physical appearance of the screen. 


This command corresponds directly to the 5250 Clear Format Table command. See the 5250 data stream 
documentation for details. 


Authorities and Locks 


None 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 
If this parameter is omitted or specified as 0, this is a direct operation and the format table is 


cleared immediately. Otherwise, this is an indirect operation and the command is stored in the 
command buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
VO; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 


was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 

CPFA303 E Error occurred for screen I/O operation. 
CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 
CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 


API Introduced: V2R3 
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Clear Screen (QsnClirScr) API 


Omissible Parameter Group: 


Mode Char(1) 
Command buffer handle Binary(4) 
Low-level environment handle Binary(4) 
Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Clear Screen (QsnClrScr) API clears the screen and sets the screen size to the specified mode. This 
command corresponds directly to the 5250 Clear Unit or Clear Unit Alternate command, depending upon 
the current screen presentation size. See the 5250 data stream documentation for details. 


Authorities and Locks 


None 


Restrictions 


If this is an indirect operation, it must be the first command in the command buffer. 


Omissible Parameter Group 
Mode 
INPUT; CHAR(1) 


The mode to place the screen in after the screen is cleared. If this parameter is omitted, a value of 0 
is assumed. 


The possible values are: 


O Indicates that the current screen size should be kept. For indirect operations where this value is 
specified, the subsequent clear operation will be based on the current screen size, not on 
whatever size the screen is when the command buffer is ultimately written out. The current 
display size will be determined using the QsnRtvMod interface. 


3 Set screen to 24x80 mode. 


4 Set screen to 27x132 mode. This value is not supported by all devices. A CPFA306 error will 
occur if an attempt is made to specify this value with a device that does not support it. 


Command buffer handle 
INPUT; BINARY(4) 
If this parameter is omitted or specified as 0, this is a direct operation and the screen is cleared 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 

CPFA303 E Error occurred for screen I/O operation. 


CPFA304 E Data-stream error &1 reported for screen I/O operation. 


CPFA306 E Command not supported by current device. 


CPFA321 E Operation not first command in command buffer. 
CPFA322 E Incorrect display mode &1 specified. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 

CPFA345 E The invite active flag is not valid. 


API Introduced: V2R3 
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Create Low-Level Environment (QsnCrtEnv) 
API 


Required Parameter Group: 


1 Low-level environment description Char(*) 


2 Length of low-level environment Binary(4) 
description 


Omissible Parameter Group: 


User Extension Information Char(*) 
Length of user extension information Binary(4) 
Low-level environment handle Binary(4) 
Error Code Char(*) 


Returned Value: 


Low-level environment handle Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Create Low-Level Environment (QsnCrtEnv) API creates an operating environment for low-level 
interface routines. 


Authorities and Locks 


Display file authority 
*USE 

Display file library authority 
*USE 

Exit routine authority 
*EXECUTE 


Required Parameter Group 


Low-level environment description 
INPUT; CHAR(*) 


The environment description for the low-level interfaces. The format of this parameter is shown in 
Format of the Low-Level Environment Description. 


Length of low-level environment description 
INPUT; Binary(4) 


The length of the low-level environment description parameter. The value specified must be 16, 36, 
or 38. 


Omissible Parameter Group 


User extension information 
INPUT; CHAR(*) 


The user extension information is used to associate data and exit routines with the low-level 
environment. This essentially enables the object-oriented programming concept of inheritance, 
allowing the low-level environment to be extended in a natural way. The user extension 
information cannot be changed once the environment has been created. The format of this 
parameter is shown in Format of the Low-Level User Environment Extension Information. 


User extension information length 
INPUT; BINARY(4) 
The length of the user extension information parameter. If this parameter is specified with a zero 


value, the user extension information parameter is ignored. If a non-zero value is specified, it must 
be 48 and the user extension parameter is required. 


Low-level environment handle 
OUTPUT; BINARY(4) 
The low-level environment that is created as a result of this operation. This handle can be used 
across activation groups if the activation group in which the handle was created is still active. 
Error code 
1/0; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Low-level environment handle 
OUTPUT; BINARY(4) 


The value for parameter 5 is returned. If an error occurs during processing, returns -1. 


Format of the Low-Level Environment Description 


| Offset 
| Dee Hex |Type Field 


[ 16 | 10 |CHAR(20) —— [Displayfile 


Format of the Low-Level User Environment Extension Information 


| Offset 
[Dec [Hex |Type _|Field 


| 0 | 0 [PTR(SPP) [User data associated with the environment 


16 | 10 |PTR(PP) |Exit routine to call when the low-level environment is 
changed 


| 32 | 20 [PTR(@PP) [Exit routine to call when the low-level environment is deleted 


Field Descriptions 


In the following descriptions, specifying the value Same indicates the current value when using the Change 
Low-Level Environment (QsnChgEnv) API. The default value refers to the value set by the Initialize 
Low-Level Environment Description (QsnInzEnvD) API. 


Alternative help key support. Specifies if the alternative help key is used. The default is no alternative 
help key support. 


The possible values for this field are: 


0 Same: Keep the current setting. 
I None: No alternative help key support is used. 


QSN_F1 through QSN_F24 The specified key is the alternative help key. See Table 1 for the values that 
correspond to these mnemonics. When this key is pressed, the AID code for 
the Help key will be returned. 


CDRA conversions to X'3F'. When CDRA conversion takes place, all characters not supported in the 
target CCSID are converted to X'3F’. Sending data containing X'3F' to the display causes adverse effects. 


This field specifies whether the DSM low-level routines are to check for X'3F' in the data to be displayed 
and perform any conversions if necessary. Conversion will be performed for both direct and indirect 
operations on data output through the QsnWrtDta and QsnWrtTDta APIs, and input through the 
QsnReadInp, QsnReadMDT, QsnReadMDTAIt, QsnReadMDTAIt, QsnReadImm, and 
QsnReadMDTImmAIt APIs. 


The default is convert if character conversion (see below) is specified as convert. Otherwise, the default is 
standard. (See Limitations and Restrictions for further details.) 


The possible values for this field are: 


O Same: Keep the current setting. 
Z Standard: Always display data as standard data with no replacement. 


2 Convert: Always check for X'3F' in data and convert to X'1F' before displaying the data and convert 
X'1F' in incoming data to X'3F’. 


Character conversion. This field specifies whether CDRA conversion takes place on the data when the job 
CCSID does not match that of the display device. Conversion will be performed for both direct and indirect 
operations on data output through the QsnWrtDta and QsnWrtTDta APIs, and input through the 
QsnReadInp, QsnReadMDT, QsnReadMDTAIt, QsnReadMDTAIt, QsnReadImm, and 
QsnReadMDTImmAlIt APIs. 


The CCSID for the display device is determined from the CHRID of the device. The default is convert if 
the job CCSID does not match that of the underlying device; otherwise, standard is the default. 


The possible values for this field are: 


O Same: Keep the current setting. 
Z Standard: Do not perform conversion. 


2 Convert: If the job CCSID does not match that of the display device and neither has the value 65535, 
perform the appropriate conversion on outgoing and incoming data. (See Limitations and Restrictions 


for further details.) 


Coexistence. Whether DSM coexists with other screen I/O methods, such as DDS- or UIM-coded 
interfaces, during the course of this application. Better performance can be achieved if coexistence is not 
required; the DSM APIs can assume the state of the device, for example, wide or normal mode. 


The default is 1. 


The possible values for this field are: 


O Same: Keep the current setting. 
7 Coexist: Other screen I/O methods are used in conjunction with DSM. 


2 Only: DSM is the only screen I/O method being used. 


Color support. This field determines the color selection used when both a monochrome and a color display 
attribute are supplied. The default is select. 


The possible values for this field are: 


O Same: Keep the current setting. 
I Mono: Always use the monochrome attributes specified regardless of the underlying device type. 
2 Always use the color attributes specified regardless of the underlying device type. 


3 Select: Select the appropriate attribute based on the underlying display type. 


DBCS support. This field specifies whether the data being sent to the display contains DBCS data. This 
field affects, for example, how data is handled within sessions. For devices that do not support DBCS data, 
the default is standard; for DBCS-capable devices, it is mixed. If a value other than standard is specified for 
a device that does not support DBCS data, a CPFA306 error will occur. 


The possible values for this field are: 


O Same: Keep the current setting. 
Z Standard: Always handle data as single-byte characters. 


2 Only: Data contains double-byte characters only. SO/SI control characters must enclose the data; these 
are not implicitly added. 


3 Either: Data contains either double-byte or single-byte characters, but not both. SO/SI control 
characters must enclose the DBCS part of the data, unless a graphic DBCS value is passed. In this 
case, extended ideographic attributes must enclose the data, which can be written using the QsnWrtDta 
API (see Write Data (QsnWrtDta) API). 


4 Mixed: Data may contain both single- and double-byte characters. All double-byte character strings 
within the data must be enclosed by SO/SI control characters. Graphic DBCS data must be enclosed by 
extended ideographic attributes as described for the preceding value. 


Display file. The name of the display file to be used. The first 10 characters contain the file name, and the 
last 10 characters contain the library name. By specifying a display file, you can, for example, direct the 
input/output of different DSM environments to different devices, and you can specify the restore display 
parameter on the display file at creation time. The default for this field is blanks, which indicate that the 
system-supplied display file should be used. 


If a file name is specified, the file must contain a record named USRRCD. This record must have the 
USRDEN keyword specified. 


Exit routine to call when low-level environment changed. Exit routine to call when the low-level 
environment is changed through the QsnChgEnv or QsnSetEnvWinMod API. For a description of the 
parameters passed to this routine, see Change Low-Level Environment Exit Routine. Specify NULL for this 


field if no exit routine is required. 


Exit routine to call when low-level environment deleted. Exit routine to call when the low-level 
environment is deleted through the QsnDItEnv API. The exit routine will be called before the environment 
itself is deleted. For a description of the parameters passed to this routine, see Delete Low-Level 


Environment Exit Routine. Specify NULL for this field if no exit routine is required. 


Invite active. This field determines whether each write that is sent out causes the device to be invited. After 
the device is invited, the user is able to enter data, but the application can continue processing instead of 
waiting for input. When the application is ready for the input, it can call QsnReadInvited, which will issue a 
read from invited device operation. 


The invite active flag is ignored by the read APIs, like QsnReadMDT. If the operation is indirect, then the 
read command will be added to the command buffer. This command buffer can be passed into the 
QsnReadInvited API, where it will be sent out before the read from invited device is done. If the operation 
is direct, then the read command will be sent in a data stream to the device. The new data stream will cause 


the invite to be retracted. A read with wait will be performed. 


If the display file value is specified for the environment, the INVITE keyword must be specified on the 
USRRCD record of the specified display file. 


The timeout value for the read from invited device operation can be controlled, by supplying a display file 
for the environment. The WAITRCD parameter on the CRTDSPF command can be set to the desired 
timeout value. See the return value for the QsnReadInvited API to determine the return value if the read 
from invited device operation times out. 


The possible values for this field are: 


O Same: Keep the current setting. 


I Not active: The INVITE keyword, if specified in the display file, will be ignored. A normal read of the 
device will be performed. 


2 Active: Any request to get data from the display will result in a read from invited device being issued. 


For more information on invite processing, see the Application Design iene book. 


Prevent override. This field determines whether the display file used by DSM can be overridden or not. 
This value is ignored if the display file value is not specified. 


The possible values for this field are: 


0 Same: Keep the current setting. 

I Do not prevent override: When opened, the display file will allow overrides. For create 
and initialize operations, this is the default. 

2 Prevent overrides: When the display file is opened, the flag to block overrides will be set. 


User data associated with the environment. A pointer to any data the user wants to associate with this 
environment. This field can be used by the programmer to attach information to the low-level environment 
that can be of any format. For example, if multiple environments are being used, a list of the fields currently 
defined in an environment could be associated with the environment through this pointer. Specify NULL 
for this field if you do not have any user data. 


Target device. The program device name of the target display device for the environment. This parameter 
must be specified with a value of “REQUESTER, which is the default. 


Exit Routine Error Handling 


If an exception occurs during the processing of an exit routine, the exception is ignored and processing 
continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an 
exit routine by adding an exception handler to the routine. 


Change Low-Level Environment Exit Routine 


This exit routine, if specified on the user extension information, is called after the environment is changed 
through the QsnChgEnv or QsnSetEnvWinMod API. The following parameter is passed to the exit routine: 


1 Low-level environment handle Input Binary(4) 


Change Low-Level Environment Exit Routine Parameter 
Low-level environment handle 
INPUT; BINARY(4) 


A handle for the environment that was changed. 


Delete Low-Level Environment Exit Routine 


This exit routine, if specified on the user extension information, is called before the environment is deleted. 
The following parameter is passed to the exit routine: 


1. ~~ Low-level environment handle Input Binary(4) 


Delete Low-Level Environment Exit Routine Parameter 
Low-level environment handle 
INPUT; BINARY(4) 


A handle for the environment that was deleted. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA31E E Required parameter &1 omitted. 

CPFA327 E Low level environment description value incorrect. 
CPFA344 E The file &2 in library &3 is not valid. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


Delete Low-Level Environment (QsnDItEnv) API 


Required Parameter: 
Low-level environment handle Binary(4) 
Omissible Parameter: 
2 Error Code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Delete Low-Level Environment (QsnDItEnv) API deallocates an operating environment for low-level 
interface routines. 


Authorities and Locks 


None 


Required Parameter 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment to be deallocated. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA317 E Cannot deallocate memory dynamically. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA334 E Low level environment handle incorrect. 
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Initialize Low-Level Environment Description 
(QsnInzEnvD) API 


Required Parameter Group: 


1. Low-level environment description Output Char(**) 


2 Length of low-level environment Input Binary(4) 
description 


Omissible Parameter: 
Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Initialize Low-Level Environment Description (QsnInzEnvD) API initializes a low-level environment 
description with default values. Unless otherwise specified in the low-level environment description in 
Format of the Low-Level Environment Description, pointer fields are set to the null pointer, numeric fields 
to 0, character flag fields to 0, and other character fields to blanks. For example, the default value for the 
color support field is 3, so this field will be set to 3. 


Authorities and Locks 


Display file authority 
*USE 

Display file library authority 
*USE 

Exit routine authority 
*EXECUTE 


Required Parameter Group 
Low-level environment description 
OUTPUT; CHAR(*) 


The low-level environment description to be initialized. 
Length of low-level environment description 
INPUT; Binary(4) 


The length of the low-level environment description parameter. This parameter must be specified as 
16, 36 or 38. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA344 E The file &2 in library &3 is not valid. 
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Query 5250 (QsnQry5250) API 


Required Parameter Group: 


1 Receiver variable Char(*) 
2 Length of receiver variable Binary(4) 


Omissible Parameter: 


3 Error Code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Query 5250 (QsnQry5250) API is used to retrieve the results of the Query 5250 command for the 
current device. The Query 5250 command returns device and controller attributes for the current device, 
such as whether wide mode and graphical user interface (GUI) are supported. 


Authorities and Locks 


None 


Restrictions 


This command is not supported by all control units. A query status of 3 indicates if the query failed. 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 


The receiver variable that is to receive the result of the query. You can specify that the size of the 
area be smaller than the format requested as long as you specify the length of the receiver variable 
parameter correctly. As a result, the API returns only the data the area can hold. The format of the 


data returned is shown in Format of the Query Data. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable. If the length is larger than the size of the receiver variable, the 
results are unpredictable. The minimum length is 8 bytes. 


The API returns as much information as it can fit in this length. If the available information is 
longer, it is truncated. If the available information is shorter, the unused output is unchanged; 
whatever is already stored in that space remains there. To determine how much information the API 
actually returns in response to this call, see the bytes returned field. To determine how much 
information the API could return if space were available, see the bytes available field. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Query Data 


[ Offset 
——— Type Field 


[8 | 8 |CHARG) [Querystaus ~~—SCSCS~S 
[14 [| E |CHARG6) [Reserved SCS 
[38 | 26 |CHARG)  [KeyboardID ———~—~SCSCS 


[40 [ 28 CHAR) [PCkeyboad SSS 
[48 [30 CHAR) [Reserved ~~~ SCS~*S 
[a | 40 |CHARG) [Reserved =~ SSCS 
[70 | 46 |CHAR@ [Reserved SCS 


Field Descriptions 


Further details on the fields listed can be found in the 5494 Remote Control Unit Functions Reference, 
SC30-3533, manual. 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 
Code Level. Identifies the code release level. 
Control unit customization. Indicates customization parameters for the control unit as: 


Byte 0 
e Bit 0: Indicates that the iSeries server can send a 5250 WSC Customization command when set on 
e Bit 1: Indicates that the iSeries server can send a 5250 Query Station State command when set on 


e Bit 2: Indicates that the iSeries server can send a 5250 Workstation Customization command to 
select the SBA code returned in READ commands for displays with ideographic extended 
attributes when set on. 


e Bit 3: Indicates that the 5250 Workstation Customization command may be either 6 bytes or greater 
than 8 bytes in length when set on. 


e Bits 4-7: Reserved 
Byte 1: Reserved 
Device capabilities. Defines the operating capabilities of the designated device as: 


Byte 0 
e Bits 0-1: Indicate Row 1/Column 1 support as: 


B'00' No support 
B01" limited support 


e Bit 2: Indicates the Read MDT Alternate command is supported when set on 

e Bit 3: Indicates the work station and control unit have PA1 and PA2 support when set on 

e Bit 4: Indicates the work station and control unit have PA3 support when set on 

e Bit 5: Indicates the work station and control unit have cursor select support when set on 

e Bit 6: Indicates the work station and control unit have move cursor order support when set on 


e Bit 7: Indicates the Read Modified Immediate Alternate command is supported when set on 


Byte 1--display screen capabilities 


e Bits 0-3: Define screen size as: 


B'0001' 24x 80 
BOOI1I' 24x 80 or 27 x 132 


e Bit 4: Indicates selector light pen (SLP) is supported when set on 
e Bit 5: Indicates magnetic stripe reader (MSR) is supported when set on 


e Bits 6-7: Define color support as: 


B'00' Monochrome display 
B'OI' Color support 


Byte 2 
e Bit 0: Indicates Text Symbols support when set on 
e Bit 1: Indicates work station and control unit have extended primary attribute 


e Bits 2-4: Indicate Office Editor/Text support as: 


B'000' No Office Editor/Text support 
B00!" single language Office Editor/Text support 
B'010' dual language Office Editor/Text support 


e Bit 5: Indicates work station and control unit have extended primary attribute support in data 
processing (DP) mode (WEA order) when set on 


e Bits 6-7: Indicates extended foreground color attribute support 


B'OI' Available in DP mode. Fourteen colors are defined, but only seven are available. The other 
seven colors are mapped into the available colors. 


B'10' Available in DP mode. Fourteen colors are supported. 


Byte 3 
e Bits 0-2: Indicate ideographic capability as: 


B'000' No ideographic capability 
B'001' Ideographic capability for presentation screen only 
B'010' \deographic data type and presentation screen ideographic capability 


e Bits 3-5: Indicate bidirectional support as: 


B'000' No bidirectional capability 
B'001' Bidirectional capability 


e Bit 6: Ideographic 
e Bit 7: Indicates CCSID-based I/O is supported when set on.*& 


Byte 4 
e Bits 0-2: Indicate graphics capability as: 


B'000' No graphics capability 
B'00I' 5292-style graphics 
B‘010' GDDM®)-OS/2®) Link Graphics 


Bit 3: Indicates extended 3270 data stream capability when set on 
Bit 4: Indicates a pointer device is available when set on 


Bit 5: Indicates that GUI-like characters are available when set on 


Bit 6: Indicates the control unit supports enhanced user interface commands and field control words 
(FCWs) when set on. 


The commands include: 
Create Window 
Unrestricted Cursor Movement 
Remove GUI Window 
Remove All GUI Constructs 
Read Screen To Print 
Read Screen To Print With Extended Attributes 


Write Error Code To Window 


Save Partial Screen 
Restore Partial Screen 
Define Selection Field 
Remove GUI Selection Field 
Define Scroll Bar 
Remove GUI Scroll Bar 

The FCWs include: 
Continued 
Cursor Progression 
Highlighted 


Pointer Device Selection 


e Bit 7: Indicates Write Error Code To Window command is supported when set on 


Byte 5 


e Bit 0: Indicates the Write Data and Programmable Mouse Buttons structured field commands, the 
Word Wrap FCW, and Ideographic Continued entry fields are supported when set on 


e Bit 1: Indicates this is a GUI device which will use all-points-addressable constructs for windows, 
selection fields, and scroll bars, when set on 


e Bits 2-7: Reserved 
Byte 6: Reserved 


Bytes 7-8: 
e Bit 0-13: Reserved 
e Bit 14-15: 5250 fax or image support 


B'00' No 5250 image or fax support 
B'OI' Support for seven formats: 
o TIFF 


No compression 


CCITT Group 3 fax one-dimensional, modified-Huffman run-length 
encoding 


mu CCITT Group 3 fax compression 
mu CCITT Group 4 fax compression 
mw PackBits run-length encoding 

o PCX monochrome format 


o Stand-alone CCITT Group 3 fax compression 


B'II' Support for the seven previous formats, plus five additional formats: 
o IOCA 
a IBM MMR algorithm 
m= No compression 


mu CCITT Group 3 fax one-dimensional, modified-Huffman run-length 
encoding 


mu CCITT Group 3 fax compression 
a CCITT Group 4 fax compression 


Byte 9: Reserved for use by PC emulators to indicate additional 5250 image or fax formats supported 


Byte 10: 


e Bit 0: Indicates printer type as: 


B’0' SCS printer 
B'I' IPDS printer 


e Bits 1-7: Reserved 
Byte 11: Reserved 
Extended keyboard ID. The device code for extended 5250 keyboards. 


Grid buffers. The number of grid buffers that are available in the device. 


X'00' Not grid-capable. 


Images or faxes. The number of images or faxes that can be presented on a display screen. 


X'00' No 5250 image or fax support 
X'01-FE' Number allowed 


X'FF' Variable, dependent on the size of the image or fax 


Image or fax scaling granularity. 


X'00' No 5250 image or fax support 


X'01' Support for scaling percentages from 3% to 400%. No scroll-bar scaling, fill scaling, no change 
scaling, increment and decrement 


X'02-7E' Reserved 
X'7F' Support for continuous scaling 


X'80-FF' Reserved for use by 5250 PWS emulators 


Image or fax rotating granularity. 


X'00' No 5250 image or fax support 
X'01' Support for rotating of 0, 90, 180, and 270 degrees 
X'02-7E' Reserved 


X'7F' Support for continuous rotation 


X'80-FF' Reserved for use by 5250 PWS emulators 


Image or fax support. 


X'00' No 5250 image or fax support 
Bo' Pop-up and pull-down windows that were written after 
image or fax are presented over image or fax data when set 
on 
B'l' This device supports transparent mode. 


B'2-7' Reserved 


Invisible tags. Defines more device capabilities of the designated device as: 
e Bits 0-5: Reserved 
e Bit 6: EBCDIC-to-ASCII translation. This is used by workstation gateway devices. 


e Bit 7: True transparency. 
Keyboard ID. Reserved. This field is set to X'00". 
Machine type code. An EBCDIC code for the machine type. 
Maximum input fields. The maximum number of input fields available (256). 
Model number. An EBCDIC code for the machine model number. 


PC keyboard ID. Device code for PC keyboards attached to a 5250 work station (X'00' for 
nonprogrammable work stations). 


Query status. The status of the 5250 query data. The possible values are: 


DSM_5250Q_YES (1) Query information successfully retrieved. 


DSM_5250Q_NO (2) Query cannot be issued for the device. This occurs when the device 
configuration specifies that the query command should not be issued against the 
device. 


DSM_5250Q_FAIL (3) Query command failed. Default values are supplied based on the device type. 
This occurs, for example, when the controller does not support the query 
command. 


Reserved. An ignored field. 


Serial number. Field for device serial number. This field is set to zero for a work station with no serial 
number. 


Type of grid line support. 

X'00' No grid line support 

X'0l' Type 1 grid line support including support for grid line commands 
Work station control unit. The type of control unit. 


Work station type code. The workstation type. The value is X'01' for display station. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 
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Query Color Support (QsnQryColorSup) API 


Omissible Parameter Group: 


Color indication Char(1) 
Low-level environment handle Binary(4) 
Error code Char(*) 


Returned Value: 


Color indication Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Query Color Support (QsnQryColorSup) API determines whether the current display device supports 
color or not. 


Authorities and Locks 


None 


Omissible Parameter Group 


Color indication 
OUTPUT; CHAR(1) 
Whether the device supports color or not. This information will be set based on the results of the 
5250 Query command, if the display supports it; otherwise, certain defaults are assumed. See 
Device Support for details. The possible values are: 
0 Device does not support color 


I Device supports color 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Color indication 
OUTPUT; BINARY(4) 


This API returns the value for the color indication parameter if successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA334 E Low level environment handle incorrect. 
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Query Display Mode Support (QsnQryModSup) 
API 


Required Parameter: 
Display mode 
Omissible Parameter Group: 


2, Mode indication Char(1) 
3 Low-level environment handle Binary(4) 
4 — Error code Char(*) 


Returned Value: 


Mode indication Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Query Display Mode Support (QsnQryModSup) API determines if the current display device supports 
the given mode. Certain devices, like the 3486 and 3487, support 27x132 mode but can be switched by 
keystroke to turn off the wide capability. This will be reflected in the result returned by the QsnQryModSup 
API. Use this API to determine if a subsequent mode change request through the Clear Screen (QsnClrScr) 
API is valid. You can use the result of the Query 5250 (QsnQry5250) API to determine if the display is 
capable of supporting wide mode or not. 


Authorities and Locks 


None 


Required Parameter 
Display mode 
INPUT; CHAR(1) 


The display mode for which to query support. The possible values are: 


3 24x80 mode 
4 27x132 mode 


Omissible Parameter Group 
Mode indication 
OUTPUT; CHAR(1) 
Whether the device allows the specified mode or not. The possible values are: 


0 Device does not support the mode 


I Device supports the mode 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Mode indication 
OUTPUT; BINARY(4) 


This API returns the value for the mode indication parameter if successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA322 E Incorrect display mode &1 specified. 
CPFA334 E Low level environment handle incorrect. 
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Restore Screen (QsnRstScr) API 


Required Parameter: 


1 Input buffer containing saved Input Binary(4) 
data 


Omissible Parameter Group: 


Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(**) 
Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Restore Screen (QsnRstScr) API restores the state of the display as saved with an indirect command. 
The display will be restored using the data contained in the input buffer given by parameter 1. If an indirect 
operation is specified, the resulting command buffer will contain the Restore Screen command and the data 
to restore the screen. Additional commands can be added to the command buffer subject to the conditions 
described in Restrictions. 


This command corresponds directly to the 5250 Restore Screen or Restore Partial Screen command. See the 
5250 data stream documentation for details. 


Authorities and Locks 


None 


Restrictions 


This command must be the last command in the command buffer except when GUI support is used. In this 
case, other input commands may follow. 


Required Parameter 


Input buffer containing saved data 
INPUT; BINARY(4) 


An input buffer that contains the result of an indirect QsnSavScr operation. The data will be copied 
from this input buffer and used for the restore screen operation. 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 
If this parameter is omitted or specified as 0, this is a direct operation and the screen is restored 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 


CPFA303 E Error occurred for screen I/O operation. 


CPFA304 E Data-stream error &1 reported for screen I/O operation. 


CPFA305 E Cannot add operation to command buffer. 
CPFA316 E Saved data not valid. 

CPFA31E E Required parameter &1 omitted. 
CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA343 E Output operation not done. 
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Retrieve Display Mode (QsnRtvMod) API 


Omissible Parameter Group: 


Display mode Char(1) 
Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value: 


Display mode Char(1) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Display Mode (QsnRtvMod) API returns the current display mode. 


Authorities and Locks 


None 


Omissible Parameter Group 


Display mode 
OUTPUT; CHAR(1) 


The current display mode. The possible values are: 


3 Device is in 24x80 mode 


4 Device is in 27x132 mode 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Display mode 
OUTPUT; CHAR(1) 


This API returns the value for the display mode parameter, or O if an error occurs during 
processing. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA322 E Incorrect display mode &1 specified. 
CPFA334 E Low level environment handle incorrect. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


Retrieve Low-Level Environment Description 
(QsnRtvEnvD) API 


Required Parameter Group: 


1. Low-level environment description Output Char(**) 


2 Length of low-level environment Input Binary(4) 
description 


Omissible Parameter Group: 


3 Low-level environment handle Binary(4) 
4 Error code Char(*) 


Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Low-Level Environment Description (QsnRtvEnvD) API returns the description 
corresponding to the specified low-level environment. 


Authorities and Locks 


None 


Required Parameter Group 


Low-level environment description 
Output; CHAR(*) 


The variable that contains the low-level environment description when the QsnRtvEnvD API has 
completed. The format of the data returned is shown in Format of the Data Returned. 


Length of low-level environment description 
INPUT; Binary(4) 


The length of the low-level environment description parameter. The minimum length is 8. If the 


length is larger than the size of the receiver variable, the results are not predictable. The API returns 
as much information as it can fit in this length. It the available information is longer, it is truncated. 
If the available information is shorter, the unused output is unchanged; whatever is already stored 
in that space remains there. To determine how much information the API actually returns in 
response to this call, see the bytes returned field. To determine how much information the API 
could return if space were available, see the bytes available field. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment for which the description should be retrieved. If this parameter is 
omitted or specified as 0, the description for the default low-level environment is retrieved. 
Error code 
1/0; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Data Returned 


| Offset 
| Dec Hex /|Type Field 


| 0 0 BINARY(4) Bytes returned 
| 4 4 BINARY(4) Bytes available 


8 8 CHAR(*) Environment description 
The format of the remaining data returned is 
shown in Format of the Low-Level Environment 
Description. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3C24 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA334 E 
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Error Message Text 

Severe error while addressing parameter list. 
Length of the receiver variable is not valid. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 


Low level environment handle incorrect. 
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Retrieve Low-Level Environment User Data 
(QsnRtvEnvDta) API 


Required Parameter: 


1 Low-level environment Binary(4) 
handle 


Omissible Parameter Group: 


2 User data pointer PTR(SPP) 
3. Error code Char(*) 


Returned Value: 


User data pointer PTR(SPP) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Low-Level Environment User Data (QsnRtvEnvDta) API returns a pointer to the user data for 
the given low-level environment. 


Authorities and Locks 


None 


Required Parameter 
Low-level environment handle 
INPUT; BINARY(4) 


A handle for the low-level environment for which the user data should be returned. If this 
parameter is omitted or specified as 0, the default low-level environment is used. 


Omissible Parameter Group 
User data pointer 
OUTPUT; PTR(SPP) 


A pointer to the user data, as specified on the low-level environment description, for the given 
low-level environment. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


User data pointer 
OUTPUT; PTR(SPP) 


This API returns the value for the user data pointer parameter, or the null pointer if an error occurs. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CI1F E Pointer is not on a 16 byte boundary. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Low-Level Environment Window Mode 
(QsnRtvEnvWinMod) API 


Required Parameter Group: 


1. Window mode description Output Char(*) 
2 Length of window mode Input Binary(4) 
description 


Omissible Parameter Group: 


3. Low-level environment Binary(4) 
handle 


4 Error Code Char(*) 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Low-Level Environment Window Mode (QsnRtvEnvWinMod) API queries the state of the 
window mode for the low-level interfaces. 


Authorities and Locks 


None 


Required Parameter Group 


Window mode description 
OUTPUT; CHAR(*) 


The field in which the window mode description should be stored. The format of the data returned 
in this field is described in Format of the Data Returned. 


Length of window mode description 
INPUT; BINARY(4) 


The length of the window mode description parameter. If the length is larger than the size of the 
receiver variable, the results are not predictable. The minimum length is 8. The API returns as 
much information as it can fit in this length. If the available information is longer, it is truncated. If 
the available information is shorter, the unused output is unchanged; whatever is already stored in 
that space remains there. To determine how much information the API actually returns in response 
to this call, see the bytes returned field. To determine how much information the API could return 
if space were available, see the bytes available field. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Data Returned 


| Offset 
| Dec | Hex /Type Field 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 
Window mode. Whether window mode is enabled or disabled. The possible values are: 


O Window mode is disabled. 


1 Window mode is enabled. 


Window mode description. The format of the remaining data returned is shown in Format of the Window 
Mode Description. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Screen Dimensions (QsnRtvScrDim) 
API 


Omissible Parameter Group: 


Number of rows Binary(4) 
Number of columns Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Screen Dimensions (QsnRtvScrDim) API retrieves the current dimensions of the screen. You 
must specify either the number-of-rows or the number-of-columns parameter, or a CPFA31E message will 
be issued. 


Authorities and Locks 


None 


Omissible Parameter Group 


Number of rows 
OUTPUT; BINARY(4) 


The current height of the screen. This information will be set based on the current display size. 
Number of columns 
OUTPUT; BINARY(4) 


The current width of the screen. This information will be set based on the current display size. 
Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 


value of zero, the default low-level environment is used. 
Error code 
1V/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA334 E Low level environment handle incorrect. 
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Roll Down (QsnRollDown) API 


Required Parameter Group: 


1 Number of lines to roll Binary(4) 
2 Top row of roll area Binary(4) 
3 Bottom row of roll area Binary(4) 


Omissible Parameter Group: 


Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Roll Down (QsnRollDown) API rolls the screen down a given number of lines within the roll area 
specified. The following conditions cause a CPFA315 error to occur: 


e A top row of zero 

e A bottom row greater than the number of display lines 

e A top row greater than or equal to the bottom row 

e A roll area greater than the bottom row minus the top row 


This API corresponds directly to the 5250 Roll command. See the 5250 data stream documentation for 
details. 


Restrictions 


The following considerations apply to the QsnRollDown API: 
e Lines vacated due to a roll are not cleared to nulls. 


e The command does not change the format table, and so, should be avoided when it could produce 
discrepancies between the format table and the display. 


e Data rolled out of the roll area are lost. 


Authorities and Locks 


None 


Required Parameter Group 


Number of lines to roll 
INPUT; BINARY(4) 


The number of lines to roll the designated area down by. 
Top row of roll area 
INPUT; BINARY(4) 


The line number defining the top line of the area that will participate in the roll. 
Bottom row of roll area 
INPUT; BINARY(4) 


The line number defining the bottom line of the area that will participate in the roll. 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 
If this parameter is omitted or specified as 0, this is a direct operation and the screen is rolled down 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA315 E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 
Roll parameters not valid. 

Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 
Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Roll Up (QsnRollUp) API 


Required Parameter Group: 


Number of lines to roll Binary(4) 
Top row of roll area Binary(4) 
Bottom row of roll area Binary(4) 


Omissible Parameter Group: 


4 Command buffer handle Binary(4) 
5 Low-level environment handle Binary(4) 
6 —_ Error code Char(*) 


Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


Usage Notes 


The Roll Up (QsnRollUp) API is identical in function to the QsnRollDown API, except the lines are rolled 
up instead of down. 


Authorities and Locks 


None 


Required Parameter Group 


Number of lines to roll 
INPUT; BINARY(4) 


The number of lines to roll the designated area up by. 


Top row of roll area 


INPUT; BINARY(4) 


The line number defining the top line of the area that will participate in the roll. 
Bottom row of roll area 
INPUT; BINARY(4) 


The line number defining the bottom line of the area that will participate in the roll. 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 
If this parameter is omitted or specified as 0, this is a direct operation and the screen is rolled up 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 


CPFA303 E Error occurred for screen I/O operation. 


CPFA304 E Data-stream error &1 reported for screen I/O operation. 


CPFA305 E Cannot add operation to command buffer. 
CPFA315 E Roll parameters not valid. 

CPFA31E E Required parameter &1 omitted. 
CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
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Save Screen (QsnSavScr) API 


Omissible Parameter Group: 


Saved data command buffer Output Binary(4) 
handle 


Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code V/O Char(*) 
Returned Value: 


Saved data command buffer Output Binary(4) 
handle 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Save Screen (QsnSavScr) API saves the current state of the display. If this is a direct operation, the 
API creates a command buffer that contains the operations used to restore the screen state and returns a 
handle for this buffer. When a direct save screen operation is issued, the saved screen data is returned in a 
command buffer. This command buffer contains the Restore Screen command along with the data to restore 
the screen. Additional commands can be added to the command buffer as described in Restrictions under 


the Restore Screen (QsnRstScr) API. The screen can be restored by sending this command buffer using the 
Put Command Buffer (QsnPutBuf) API. 


When an indirect save screen operation is issued, the Save Screen command is stored in the command 
buffer and is considered an input operation. The command can be issued to the screen only through the Put 
Command Buffer and Perform Get (QsnPutGetBuf) API. The saved data will be returned in the input buffer 
parameter specified for the QsnPutGetBuf API. The screen can subsequently be restored by specifying this 
input buffer on the QsnRstScr API. 


This command corresponds directly to the 5250 Save Screen (when the underlying control unit supports it) 
or Save Partial Screen command. See the 5250 data stream documentation for details. 


Authorities and Locks 


None 


Restrictions 


This command must be the last command in the command buffer, except when GUI support is available. In 
this case, other non-input commands may follow. 


Omissible Parameter Group 


Saved data command buffer handle 
OUTPUT; BINARY(4) 


The variable that will contain the command buffer handle for the restore screen operation if this is a 
direct operation. 


For an indirect operation, the result of the save screen will be returned in the input buffer of a 

subsequent input operation, which can be used to restore the screen using the QsnRstScr operation. 
Command buffer handle 

INPUT; BINARY(4) 

If this parameter is omitted or specified as 0, this is a direct operation and the screen is saved 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Saved data 
OUTPUT; BINARY(4) 


For a successful operation, this API returns the value for the saved data parameter if this is a direct 
operation; otherwise, it returns zero. For an unsuccessful operation, it returns -1. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 


CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA313 E 
CPFA314 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 


Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Command buffer already contains an input operation. 
Memory allocation error. 

Buffer handle incorrect. 

Low level environment handle incorrect. 


Output operation not done. 
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Set Low-Level Environment Window Mode 
(QsnSetEnvWinMod) API 


Required Parameter: 
Enable window mode 
Omissible Parameter Group: 


Previous window mode setting Char(1) 
Window mode description Char(*) 
Length of window mode description Binary(4) 
Low-level environment handle Binary(4) 
Error Code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API enables or disables the window 
mode for the low-level environment. Use this API to affect how row and cursor positions specified on 
low-level interface operations are interpreted for operations to the given low-level environment. Additional 
details regarding windows can be found in Introduction to the Window Services APIs. 


When window mode is enabled, screen locations and cursor positions specified and retrieved in the 
low-level interface routines are interpreted relative to the logical window area defined. The logical window 
area is treated as a logical screen in terms of validity of cursor and data starting positions. If an attempt is 
made to write data or define a field that starts outside of the current window area, a CPFA31D error is 
issued for that particular API. If data or a field is written to the window that exceeds the window boundary, 
no error condition occurs and the data or field is truncated. 


The size of the logical window area can be determined through the Retrieve Low-Level Environment 
Window Mode (QsnRtvEnvWinMod) API. When window mode is enabled, screen addresses must be 
explicitly specified for APIs such as the QsnWrtDta API in order for the address to be interpreted relative to 
the window area. If a screen address is not specified, the current display address will be used as an absolute 
screen address irrespective of the current window mode. This is because the current screen address is not 
tracked by DSM, but is handled by the control unit. 


When window mode is enabled, APIs where a cursor position is specified, such as the QsnSetFld API, issue 
a CPFA307 error if the given cursor position is outside the bounds of the current window area. For APIs 
that return a cursor position, such as the Get Cursor Address (QsnGetCsrAdr) API, both the row and 
column returned will be -1 if the cursor screen location is outside of the current window area, O if the cursor 


is on the top or left border, or the number of screen rows or columns plus 1 if the cursor is on the bottom or 
center border of the window area, respectively. The following low-level APIs are affected by the window 
mode: 


QsnRtvReadAdr 
QsnRtvFldInf 
QsnGetCsrAdr 
QsnGetCsrAdrAID 
QsnSetOutAdr 
QsnWrtDta 
QsnWrtSFMaj 
QsnWrtTDta 
QsnWrtExtAtr 
QsnWrtPad 
QsnWrtPadAdr 
QsnSetFld 
QsnSetCsrAdr 
QsnInsCsr 
QsnSetErr 


The actual screen location used for a screen I/O operation is calculated using the formula 
base+offset=actual, where base is the upper left row/column location of the window border (0 for full 
screen) if offset is positive and the lower center row/column location of the window border (screen 
height/width plus 1 for full screen), if offset is negative, offset is the row/column specified on the API, and 
actual is the actual screen location. For example, if the window area were defined to be from row 3, column 
10 with 15 rows and 30 columns, as shown in Figure 1, then an attempt to position the cursor through the 
QsnSetCsrAdr API at row 4, column 5 would actually position the cursor on the screen at row 7, column 
15, as indicated by the letter a in Figure 1. Specifying row 9, column -7 would position the cursor on the 


screen at row 12, column 34 (b in Figure 1). An attempt to position the cursor at error issue a CPFA307 


error row 16, column 5 would result error (Screen position &1,&2 outside of display or window area). since 
this position is outside the bounds of the current window area. Given the same window area description, a 
call to the QsnRtvFldInf API specifying an input buffer containing a field read from row 10, column 20 on 
the actual screen (the c in Figure 1), would return a field row and column location of 7 and 10 respectively. 
A call to the QsnGetCsrAdr API would return -1,-1 if the cursor were located outside of the window area, 
such as in row 18 column 32. 


Enabling or disabling the window mode does not affect any data currently displayed on the screen or the 
behavior of any commands stored previously in a command buffer. For example, if the window mode was 
enabled as described above and the QsnSetCsrAdr API was called as an indirect operation specifying row 4 
and column 5, the cursor position command stored in the command buffer would reflect the current window 
mode. Whenever that command buffer is written out, the cursor would always be set on the screen at row 6, 
column 14, regardless of whether or not window mode was disabled or changed at the point when the 
command buffer was written to the screen. 


Figure 1. Window Area 


Authorities and Locks 


None 


Required Parameter 
Window mode 
INPUT; CHAR(1) 
Whether window mode should be enabled or disabled. The possible values are: 


0 Disable window mode 


1 Enable window mode 


Window mode is initially disabled. 


Omissible Parameter Group 


Previous window mode setting 
OUTPUT; CHAR(1) 


Whether window mode was enabled or disabled prior to this API being called. The possible values 
returned are: 


0 Window mode was disabled prior to this API being called 
I Window mode was enabled prior to this API being called 


Window mode description 
INPUT; CHAR(*) 


The window mode description. If this parameter is omitted or the length parameter is specified as 0, 
and window mode is to be enabled, the values from the previous window mode setting will be used. 
If no such values exist, the current screen size will be used. The window area described must fall 
within the bounds of the current screen size. in a CPFA307 error (Screen position &1,&2 outside of 
display or window area). The format of this field is shown in Format of the Window Mode 


Description. 


This parameter is ignored if window mode is to be disabled. 
Length of window mode description 
INPUT; BINARY(4) 
The length of the window mode description parameter. If this parameter is specified, it must be 


either 0, in which case the window mode description parameter is ignored, or exactly 13 bytes in 
which case the window mode description is required. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
V/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Window Mode Description 


| Offset 
| Dec Hex |Type Field 


| 0 0 [CHAR(1) [Attribute column indication 

| 1 1 [BINARY (4) [Upper left row of window area border 

| 5 5 [BINARY (4) [Upper left column of window area border 
| 9 9 [BINARY (4) [Number of rows in window area 

| 13 D [BINARY (4) [Number of columns in window area 


Field Descriptions 


Attribute column indication. Whether the column containing the left border of the logical window is an 
attribute column. Operations such as QsnWrtDta can specify column 1 for the data location and specify a 
leading attribute. In this case the data will be written to the first column of the window area and the 
attribute will be written to the column containing the logical window border. If the attribute column is not 
specified for the window area, such an operation would result in a CPFA31D error (Attempt to write 
outside of window area.). This column would also be used to insert the leading attribute when line 
wrapping occurs within the window. 


The allowable values are: 

O No attribute column 

7 Attributes can be written to column containing left logical window border 
Number of columns in window area. The number of columns in the window area. 
Number of rows in window area. The number of rows in the window area. 


Upper left column of window area border. The column location of the leftmost column in the window 
area. This parameter must be a value between 0 and the screen width inclusive. 


Upper left row of window border. The row location of the upper border of the logical window area. This 
parameter must be a value between 0 and the screen height inclusive. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 


CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPFA31E E Required parameter &1 omitted. 
CPFA324 E Window area definition is incorrect. 
CPFA32A E Window mode indicator must be '0' or '1'. 
CPFA334 E Low level environment handle incorrect. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


Buffer Manipulation and Query APIs 


The buffer manipulation and query APIs are used to create, query, and manipulate input and command 
buffers that interact with the screen. 


The two buffer types used by the low-level interfaces are command and input. A command buffer can be 
used to accumulate a sequence of low-level commands without performing an I/O operation. The entire 
buffer can be written out at once in a single I/O operation. See Direct and Indirect Operations for further 


discussion of command buffers. When an input operation is performed, you can specify an input buffer as 
the target of the operation. The input results are placed in this buffer, which can then be queried through 
several interfaces. You may query for individual pieces of information, such as the AID byte from the input 
operation using the Retrieve AID Code on Read (QsnRtvReadAID) API or for multiple pieces of 
information using the Retrieve Read Information (QsnRtvReadInf) API. 


Command and input buffers can be used across activation groups if the activation group in which the buffer 
was created still exists. 


The buffer manipulation and query interfaces are: 


e Clear Buffer (QsnClrBuf) clears all commands or data in a buffer resets its state. 
e Copy Buffer (QsnCpyBuf) copies the contents of one buffer to another. 


e Create Command Buffer (QsnCrtCmdBuf) creates a command buffer to accumulate low-level 
commands. 


e Create Input Buffer (QsnCrtInpBuf) creates an input buffer to receive input results. 


e@ Delete Buffer (QsnDItBuf) deletes a buffer. 


e@ Put Command Buffer (QsnPutBuf) sends the commands in a command buffer to the screen. 


e Put Command Buffer and Perform Get (QsnPutGetBuf) sends the commands in a command buffer 
to the screen and performs a read operation. 

e Retrieve AID Code on Read (QsnRtvReadAID) determines the Aid code for a given input 
operation. 


e Retrieve Available Data (QsnRtvAvailData) copies the user's data into an input buffer. 


e Retrieve Buffer Data Length (QsnRtvBufLen) returns the length of data in a buffer. 


e Retrieve Buffer Size (QsnRtvBufSiz) returns the size of a buffer. 


e Retrieve Cursor Address on Read (QsnRtvReadAdr) retrieves the cursor position at the completion 
of an input operation. 


e Retrieve Field Information (QsnRtvFldInf) returns information about a particular field in an input 
buffer. 

e Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) retrieves the number of data bytes in an 
input buffer after an input operation. 

e Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) retrieves the number of bytes of field 
data after an input operation. 


e Retrieve Number of Bytes Read from Screen (QsnRtvReadLen) retrieves the number of data bytes 
read from the screen after an input operation. 


e@ Retrieve Number of Fields Read (QsnRtvFldCnt) retrieves the number of fields in an input buffer. 


e Retrieve Pointer to Data in Input Buffer (QsnRtvDta) returns a pointer to the first byte of input data 
in an input buffer. 


e Retrieve Pointer to Field Data (QsnRtvFldDta) returns a pointer to the first byte of field data in an 
input buffer. 


e Retrieve Read Information (QsnRtvReadInf) returns information about the input operation. 
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Clear Buffer (QsnClirBuf) API 


Required Parameter Group: 

1 Buffer handle Binary(4) 
Omissible Parameter: 

2 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Clear Buffer (QsnClrBuf) API clears all commands or data and resets the state of the given buffer. This 
is the only API that clears or removes data in a buffer. 


Authorities and Locks 


None 


Required Parameter 


Buffer handle 
INPUT; BINARY(4) 


A handle for the buffer to be cleared. The storage associated with the buffer is not deallocated. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 
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Copy Buffer (QsnCpyBuf) API 


Required Parameter Group: 


1 Source buffer handle Binary(4) 
2 Target buffer handle Binary(4) 


Omissible Parameter: 


3 Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Copy Buffer (QsnCpyBuf) API copies the contents of one buffer to another buffer. Both buffers must 
be the same type--command or input. If the target and source buffers are the same, no operation takes place 
and no error is reported. 


If a target command buffer contains data, the data in the source buffer is appended to the target buffer. A 
CPFA301 error is issued if the target command buffer is not large enough to hold the contents of the source 
buffer and cannot be resized. 


If input buffers are being copied, the target buffer must be empty. If the target input buffer is not large 
enough to hold the data from the source buffer, the data is truncated and no error is reported. 


Authorities and Locks 


None 


Required Parameter Group 


Source buffer handle 
INPUT; BINARY(4) 
A handle for the buffer from which data is to be copied. The contents of this buffer are not affected 
by this operation. 

Target buffer handle 


INPUT; BINARY(4) 


A handle for the buffer to which data is to be copied. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA305 E Cannot add operation to command buffer. 

CPFA301 E Command buffer is full. 

CPFA313 E Command buffer already contains an input operation. 
CPFA31E E Required parameter &1 omitted. 

CPFA330 E Buffer type mismatch. 

CPFA331 E Buffer handle incorrect. 
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Create Command Buffer (QsnCrtCmdBuf) API 


Required Parameter: 
1 Initial command buffer size Input Binary(4) 
Omissible Parameter Group: 


Increment amount Input Binary(4) 
Maximum size Input Binary(4) 
Command buffer handle Output Binary(4) 
Error code V/O Char(*) 


Returned Value: 
Command buffer handle Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Create Command Buffer (QsnCrtCmdBuf) API creates a command buffer for use with low-level 
operations that accept a command buffer parameter. 


Authorities and Locks 


None 


Required Parameter 


Initial command buffer size 
INPUT; BINARY(4) 


The initial size of the command buffer, in bytes, to create. This parameter must be greater than 0 
and less than the size of the underlying display file I/O buffer: approximately 4500 bytes for 24x80, 
6300 bytes for 27x132, 8000 bytes for DBCS-capable displays, 8800 bytes for DBCS presentation 
screen-capable displays, and 16000 bytes for DBCS ideographic-capable displays. 


Omissible Parameter Group 


Increment amount 
INPUT; BINARY(4) 


The amount to increment the command buffer size by if there is not enough space to store a 
specified command. If this parameter is omitted or specified with a zero value, the buffer size will 
not be incremented and a CPFA301 error will be issued when there is no space in the buffer to store 
a requested command. If an attempt is made to increment a command buffer to a size that exceeds 
the available memory resources or the size of the underlying display file I/O buffer, the increment 
will not take place and a CPFA301 error will be issued for that operation. 


Maximum size 
INPUT; BINARY(4) 


The maximum size to increment the command buffer to when there is not enough space to store a 
specified command. If this parameter is nonzero, it must be greater than the initial command buffer 
size parameter, and less than the size of the underlying display file I/O buffer. If this parameter is 
omitted or specified with a zero value, no maximum value is assigned for the command buffer. If 
the buffer is to be incremented, it will be incremented until either there is no additional storage 
available or the command buffer exceeds the size of the display file I/O buffer. If the increment 
amount parameter is omitted or specified with a zero value, this parameter is ignored and the 
maximum size is the same as the initial command buffer size. 


Command buffer handle 
OUTPUT; BINARY(4) 


The variable containing the handle for the command buffer created after the QsnCrtCmdBuf API 
has completed. The buffer state will be the same as that following a QsnClrBuf operation. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Command buffer handle 
OUTPUT; BINARY(4) 


This API returns the value for the command buffer handle parameter if successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E 
CPFA312 E 


Error(s) occurred during running of &1 API. 
Buffer size parameter error. 
CPFA314 E Memory allocation error. 
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Create Input Buffer (QsnCrtinpBuf) API 


Required Parameter: 
1 Input buffer size Binary(4) 
Omissible Parameter Group: 


Increment amount Binary(4) 
Maximum size Binary(4) 
Input buffer handle Binary(4) 
Error code Char(*) 


Returned Value: 


Input buffer handle Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Create Input Buffer (QsnCrtInpBuf) API creates an input buffer for use with low-level commands that 
accept an input buffer parameter. 


Authorities and Locks 


None 


Required Parameter 


Input buffer size 
INPUT; BINARY(4) 


The size of the input buffer, in bytes, to create. This parameter must be greater than 0 and less than 
the size of the underlying display file I/O buffer: approximately 4500 bytes for 24x80, 6300 bytes 
for 27x132, 8000 bytes for DBCS-capable displays, 8800 bytes for DBCS presentation 
screen-capable displays, and 16000 bytes for DBCS ideographic-capable displays. 


Omissible Parameter Group 


Increment amount 


INPUT; BINARY(4) 


The amount to increment the buffer size by if there is not enough space to store a read operation. If 
this parameter is omitted or specified with a zero value, the buffer size is not be incremented and 
input data is truncated if there is not enough space. 


Maximum size 


INPUT; BINARY(4) 


The maximum size to increment the input buffer to when there is not enough space to store the 
result of a read operation. If this parameter is nonzero, it must be greater than the initial input buffer 
size parameter, and less than the size of the underlying display file I/O buffer. If this parameter is 
omitted or specified with a zero value, no maximum value is assigned for the input buffer, if the 
buffer is to be incremented, it will be incremented until either there is no additional storage 
available or the input buffer exceeds the size of the display file I/O buffer. If the increment amount 
parameter is omitted or specified with a zero value, this parameter is ignored and the maximum size 
is the same as the initial input buffer size. 


Input buffer handle 


OUTPUT; BINARY(4) 


The variable containing the handle for the created input buffer after the QsnCrtInpBuf API has 
completed. The buffer state becomes the same as that following a QsnClrBuf operation. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Input buffer handle 


OUTPUT; BINARY(4) 


This API returns the value for the input buffer handle parameter, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA312 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 


Buffer size parameter error. 


CPFA314 E Memory allocation error. 
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Delete Buffer (QsnDItBuf) API 


Required Parameter Group: 


1 Buffer handle 


Omissible Parameter: 


2 Error code 


Returned Value: 


Return code Output 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


Binary(4) 


Binary(4) 


The Delete Buffer (QsnDItBuf) API deletes a command or input buffer created with the Create Command 
Buffer (QsnCrtCmdBuf) or the Create Input Buffer (QsnCrtInpBuf) API, respectively. All storage 


associated with the buffer is deallocated. 


Authorities and Locks 


None 


Required Parameter 


Buffer handle 
Input; BINARY(4) 


A handle for the buffer to be deleted. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 
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Put Command Buffer (QsnPutBuf) API 


Required Parameter Group: 
1 Command buffer handle Binary(4) 
Omissible Parameter Group: 


2 Low-level environment Binary(4) 
handle 


3. Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Put Command Buffer (QsnPutBuf) API sends the commands accumulated in a command buffer to the 
screen. This corresponds to a write operation to the display file. If the command buffer contains no data, the 
operation returns successfully, but no I/O operation is performed. 


Authorities and Locks 


None 


Required Parameter 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer. The command buffer is not modified in any way as a result of 
this command. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA303 E 
CPFA304 E 
CPFA308 E 
CPFA309 E 
CPFA30A E 
CPFA30B E 
CPFA30C E 
CPFA316E 
CPFA31B E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA338 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Attempt to write data past end of display. 

Invalid cursor position in command buffer. 

Field length &1 not valid. 

Invalid starting address for field. 

Maximum allowable number of fields exceeded. 
Saved data not valid. 

From position &1, &2 greater than to position &3, &4. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Command buffer contains an input operation. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Put Command Buffer and Perform Get 
(QsnPutGetBuf) API 


Required Parameter Group: 


1 Command buffer handle Binary(4) 
2 Input buffer handle Binary(4) 


Omissible Parameter Group: 


3 Low-level environment Binary(4) 
handle 


4 Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Put Command Buffer and Perform Get (QsnPutGetBuf) API sends the commands accumulated in a 
command buffer to the screen and performs a read operation. The command buffer must contain an input 
operation. If it has no input operation, a CPFA333 error occurs. 


Authorities and Locks 


None 


Required Parameter Group 
Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer to be sent to the screen. 
Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 


value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA303 E 
CPFA304 E 
CPFA308 E 
CPFA309 E 
CPFA30A E 
CPFA30B E 
CPFA30C E 
CPFA316 E 
CPFA31B E 
CPFA31E E 
CPFA331 E 
CPFA334 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Attempt to write data past end of display. 

Invalid cursor position in command buffer. 

Field length &1 not valid. 

Invalid starting address for field. 

Maximum allowable number of fields exceeded. 
Saved data not valid. 

From position &1, &2 greater than to position &3, &4. 
Required parameter &1 omitted. 

Buffer handle incorrect. 


Low level environment handle incorrect. 


CPFA338 E Command buffer contains an input operation. 


CPFA343 E Output operation not done. 
CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
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Retrieve AID Code on Read (QsnRtvReadAID) 
API 


Required Parameter: 


1 Input buffer handle Binary(4) 


Omissible Parameter Group: 


2 AID code Char(1) 
3 Error code Char(*) 


Returned Value: 


AID code 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve AID Code on Read (QsnRtvReadAID) API determines the AID code corresponding to the 
input operation that filled the given input buffer. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. The input buffer must 
be filled as a result of a Read Input Fields (QsnReadInp), Read Modified Fields (QsnReadMDT), or 
Read Modified Alternate (QsnReadMDTAIt) operation. If the input buffer is filled as a result of 
any other input operation, a CPFA32E error is issued. 


Omissible Parameter Group 
AID code 
OUTPUT; CHAR(1) 


The variable that contains the AID code when the QsnRtvReadAID API has completed. See 
AID-Generating Keys for a description of the possible values. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


AID code 
OUTPUT; CHAR(1) 


This API returns the value for the AID code parameter or X'00' if an error occurs during 
processing. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 

CPFA32E E Input data for query operation incorrect. 
CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Available Data (QsnRtvAvailData) API 


Required Parameter Group: 


1 Input buffer handle Binary(4) 
2 Read command used Binary(4) 


Omissible Parameter Group: 
3 Error code Char(*) 
Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Available Data (QsnRtvAvailData) API is used to retrieve invited available data. If the invite 
active flag is on in a low-level environment description when an output operation is done, the end user is 
able to enter data. If a subsequent output operation is done, without checking for input using the 
QsnReadInvited API, and the user has entered data, DSM will store the end user's data in an internal input 
buffer and issue CPFA343. The Retrieve Available Data (QsnRtvAvailData) API will copy the data into the 
specified input buffer, as well as return the read command that is used to fill the buffer. 


Authorities and Locks 


None 


Required Parameter Group 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer where available data should be moved. 
Read command used 
OUTPUT; CHAR(1) 


The read command that was used to fill the input buffer. This can be used to determine what buffer 
manipulation API to use to retrieve the data from the input buffer. The possible values are: 


X'42' Read input fields 
X'52' Read MDT fields 
X'72' Read immediate 
X'82' Read MDT alternate 


Omissible Parameter Group 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 

CPFA320 E Pointer parameter is null. 

CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 
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Retrieve Buffer Data Length (QsnRtvBufLen) 
API 


Required Parameter Group: 
1 Buffer handle Binary(4) 
Omissible Parameter Group: 


2 Buffer data length Binary(4) 
3. Error code Char(*) 


Returned Value: 


Buffer data length Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Buffer Data Length (QsnRtvBufLen) API returns the number of bytes of command data in a 
command buffer or of input data in an input buffer. After an indirect operation is applied to a command 
buffer, the QsnRtvBufLen API result reflects the increase in the underlying command stream to 
accommodate the command. 


Authorities and Locks 


None 


Required Parameter 


Buffer handle 
INPUT; BINARY(4) 


A handle for the buffer to be queried. 


Omissible Parameter Group 
Buffer data length 
OUTPUT; BINARY(4) 


The variable containing the buffer data length after the QsnRtvBufLen API has completed. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Buffer data length 
OUTPUT; BINARY(4) 


This API returns the value for the buffer data length parameter, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 
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Retrieve Buffer Size (QsnRtvBufSiz) API 


Required Parameter Group: 
1 Buffer handle Binary(4) 
Omissible Parameter Group: 


2 Buffer size Binary(4) 
3 Error code Char(**) 


Returned Value: 
Buffer size Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Buffer Size (QsnRtvBufSiz) API returns the total number of bytes allocated for a command or 
input buffer. The result returned from this API is the current allocated buffer size, including any increments 
that may have taken place. 


Authorities and Locks 


None 


Required Parameter 


Buffer handle 
INPUT; BINARY(4) 


A handle for the buffer to be queried. 


Omissible Parameter Group 


Buffer size 
OUTPUT; BINARY(4) 


The variable containing the buffer size after the QsnRtvBufSiz API has completed. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Buffer size 
OUTPUT; BINARY(4) 


This API returns the value for the buffer size parameter, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 
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Retrieve Cursor Address on Read 
(QsnRtvReadAdr) API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group: 


Cursor row Binary(4) 
Cursor column Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Cursor Address on Read (QsnRtvReadAdr) API determines the row and column position of 
the cursor when the input operation that filled the given input buffer has completed. You must specify at 
least one of the cursor row or the cursor column parameter. If both of these parameters are omitted, a 
CPFA31E error occurs. 


The input buffer must be filled as a result of a Read Input Fields (QsnReadInp), Read Modified Fields 
(QsnReadMDT), Read Modified Alternate (QsnReadMDTAIt), Read Immediate (QsnReadImm), or Read 


Modified Immediate Alternate (QsnReadMDTImmAIt) operation. If the input buffer is filled as a result of 
any other input operation, a CPFA32E message is issued. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 


Omissible Parameter Group 


Cursor row 
OUTPUT; BINARY(4) 
The variable that contains the row position of the cursor when the QsnRtvReadAdr API has 
completed. 
Cursor column 
OUTPUT; BINARY(4) 
The variable that contains the column position of the cursor when the QsnRtvReadAdr API has 
completed. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 
CPFA32E E Input data for query operation incorrect. 
CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Field Information (QsnRtvFldinf) API 


Required Parameter Group: 


1 Input buffer handle Binary(4) 
2 Field number Binary(4) 
3 Receiver variable Char(*) 
4 Length of receiver variable Bin(4) 


Omissible Parameter Group: 


5 Low-level environment Binary(4) 
handle 


6 Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Field Information (QsnRtvFldInf) API retrieves information about a field in an input buffer 
filled by a Read Modified Fields (QsnReadMDT), Read Modified Alternate (QsnReadMDTAIt), or Read 
Modified Immediate Alternate (QsnReadMDTImmAIt) operation. 

To query the results from a Read Input Fields (QsnReadInp) or Read Immediate (QsnReadImm) operation, 
use the Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) and Retrieve Pointer to Field Data 


(QsnRtvFldDta) APIs. To query the result from any other input operations, use the Retrieve Length of Data 
in Input Buffer (QsnRtvDtaLen) and Retrieve Pointer to Data in Input Buffer (QsnRtvDta) APIs. 


Authorities and Locks 


None 


Required Parameter Group 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 


Field number 
INPUT; BINARY(4) 
The number of the field to query, specified as n, where n is the nth field in the input buffer. The 
value specified must not be greater than the field count returned by the read operation. 
Receiver variable 
Output; CHAR(*) 


The structure that will contain the result of the query when the QsnRtvFldInf API has completed. 
Length of receiver variable 
Input; BINARY(4) 


The length of the receiver variable parameter. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
I/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Query Input Field Result 


| Offset 
| Dec | Hex /|Type Field 


[| 13 [| D_ |BINARY(@) ~~ [Column position of field = 
[ 17 | 11 |BINARY(@) —— [Lengthofdataread = 
[ 21 [| 15  |CHARGI) ~~ [Reserved 
| 32 | 20 |PTR(SPP) ——— [Pointertofielddata = 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 

Column position of field. The column position relative to the window of the specified field on the screen. 
Length of data read. The length of the data read from the specified field. 

Pointer to field data. A pointer to the data for the specified field. 

Row position of field. The row position relative to the window of the specified field on the screen. 


Type of field. The type of the specified field. The possible values are: 


Value Description 
I Normal field 
2 Transparent field 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31A E Incorrect field number value &1 specified. 
CPFA31E E Required parameter &1 omitted. 

CPFA32E E Input data for query operation incorrect. 
CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 


CPFA334 E 


Low level environment handle incorrect. 
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Retrieve Length of Data in Input Buffer 
(QsnRtvDtaLen) API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group: 


2 Input data length Binary(4) 
3 Error code Char(*) 


Returned Value: 


Input data length Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) API determines the number of bytes of input 
data contained in an input buffer after an input operation. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 


Omissible Parameter Group 


Input data length 
OUTPUT; BINARY(4) 


The variable that contains the input data length when the QsnRtvDtaLen API has completed. This 
number may be smaller than the number of bytes actually read if the input buffer was not large 
enough to hold all the data. Use the Retrieve Number of Bytes Read from Screen (QsnRtvReadLen) 
API to determine the amount of data actually read from the screen. If the value returned by the 
QsnRtvReadLen API is less than the input data length, then truncation of the input data occurred. 


Returned Value 


Input data length 
OUTPUT; BINARY(4) 


This API returns the value for the input data length parameter, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 

CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Length of Field Data in Buffer 
(QsnRtvFidDtaLen) API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group: 


2 Length of field data Binary(4) 
3 Error code Char(*) 


Returned Value: 
Length of field data Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) API determines the number of bytes of 
field data returned after a Read Input Fields (QsnReadInp) or Read Immediate (QsnReadImm) input 
operation. You can use the Retrieve Pointer to Field Data (QsnRtvFldDta) API to retrieve a pointer to this 
data so that you can parse the field values. Refer to the Read Input Fields (QsnReadInp) API for a 
description of the format of the data returned. 


To query the results from a Read Modified Fields (QsnReadMDT), Read Modified Alternate 
(QsnReadMDTAIt), or Read Modified Immediate Alternate (QsnReadMDTImmAlt) operation, use the 
Retrieve Number of Fields Read (QsnRtvFldCnt) and Retrieve Field Information (QsnRtvFldInf) APIs. To 
query the result from any other input operation, use the Retrieve Length of Data in Input Buffer 
(QsnRtvDtaLen) and Retrieve Pointer to Data in Input Buffer (QsnRtvDta) APIs. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. The input buffer must 
be filled as a result of a QsnReadInp or QsnReadImm operation. 


Omissible Parameter Group 


Length of field data 
OUTPUT; BINARY(4) 
The variable that contains the field data length when the QsnRtvFldDtaLen API has completed. 


The field data length is 3 bytes less than the value returned by the QsnRtvDtaLen API. (The cursor 
and AID-key values account for the first 3 bytes of the input data returned). 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Length of field data 
OUTPUT; BINARY(4) 


This API returns the value for the length of field data parameter, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 

CPFA32E E Input data for query operation incorrect. 
CPFA32F E Buffer type incorrect. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Number of Bytes Read from Screen 
(QsnRtvReadLen) API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group 


2 Read data length Binary(4) 
3 Error code Char(*) 


Returned Value: 


Read data length Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Number of Bytes Read from Screen (QsnRtvReadLen) API returns the number of bytes of 
data read from the screen into an input buffer after an input operation. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 


Omissible Parameter Group 


Read data length 
OUTPUT; BINARY(4) 


The variable that contains the read data length when the QsnRtvReadLen API has completed. This 
number may be larger than the number of bytes actually contained in the buffer if the input buffer 
was not large enough to hold all the data. Use the Retrieve Length of Data in Input Buffer 
(QsnRtvDtaLen) API to determine the amount of data contained in the buffer or to determine if 
truncation occurred. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Read data length 
OUTPUT; BINARY(4) 


This API returns the value for the read data length parameter, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA319 E No data in input buffer. 

CPFA31E E Required parameter &1 omitted. 

CPFA320 E Pointer parameter is null. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
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Retrieve Number of Fields Read 
(QsnRtvFldCnt) API 


Required Parameter Group: 


1 Input buffer handle Binary(4) 


Omissible Parameter Group: 


2 Field count Binary(4) 
3 Error code Char(**) 


Returned Value: 


Field count Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Number of Fields Read (QsnRtvFldCnt) API returns the number of fields contained in an 
input buffer after a Read Modified Fields (QsnReadMDT), Read Modified Alternate (QsnReadMDTAIt), or 
Read Modified Immediate Alternate (QsnReadMDTImmAIt) operation. Use the Retrieve Field Information 
(QsnRtvFldInf) API to retrieve information about a specific field. 


To query the results from a QsnReadInp or QsnReadImm operation, use the Retrieve Length of Field Data 
in Buffer (QsnRtvFldDtaLen) and Retrieve Pointer to Field Data (QsnRtvFldDta) APIs. To query the result 


from any other input operation, use the Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) and 
Retrieve Pointer to Data in Input Buffer (QsnRtvDta) APIs. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. The input buffer must 
be filled as a result of a QsnReadMDT, QsnReadMDTAIt, or QsnReadMDTImmA It operation. 


Omissible Parameter Group 


Field count 


OUTPUT; BINARY(4) 


The variable that contains the field count when the QsnRtvFldCnt API has completed. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Field count 


OUTPUT; BINARY(4) 


This API returns the value for the field count parameter, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA314E 
CPFA319 E 
CPFA31E E 
CPFA32E E 
CPFA32F E 
CPFA331 E 
CPFA334 E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Memory allocation error. 

No data in input buffer. 

Required parameter &1 omitted. 

Input data for query operation incorrect. 
Buffer type incorrect. 

Buffer handle incorrect. 


Low level environment handle incorrect. 
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Retrieve Pointer to Data in Input Buffer 
(QsnRtvDta) API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group: 


2 Pointer to input data PTR(SPP) 
3 Error code Char(*) 


Returned Value: 


Pointer to input data PTR(SPP) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Pointer to Data in Input Buffer (QsnRtvDta) API returns a pointer to the first byte of input 
data in an input buffer after a read operation. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 


Omissible Parameter Group 


Pointer to input data 
OUTPUT; PTR(SPP) 


The variable that contains the pointer to the input data after the QsnRtvDta API has completed. 

You can use the Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) API to retrieve the length 
of this data. Refer to the appropriate read operation for a description of the format of the data 
returned. The value returned by this API is equivalent to the data returned by the system on an 
input operation. This parameter must be on a 16-byte boundary. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Pointer to input data 


OUTPUT; PTR(SPP) 


This API returns the value for the pointer to input data parameter, or the null pointer otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CI1F E 
CPF3CF1 E 
CPF3CF2 E 
CPFA319 E 
CPFA31E E 
CPFA32F E 
CPFA331 E 
CPFA334 E 
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Error Message Text 

Severe error while addressing parameter list. 
Pointer is not on a 16 byte boundary. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
No data in input buffer. 

Required parameter &1 omitted. 

Buffer type incorrect. 

Buffer handle incorrect. 


Low level environment handle incorrect. 
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Retrieve Pointer to Field Data (QsnRtvFidDta) 
API 


Required Parameter Group: 
1 Input buffer handle Binary(4) 
Omissible Parameter Group: 


2 Pointer to field data Output PTR(SPP) 
3. Error code V/O Char(*) 


Returned Value: 


Pointer to field datacenter Outputcenter PTR(SPP)center 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Pointer to Field Data (QsnRtvFldDta) API returns a pointer to the first byte of field data in an 
input buffer after a Read Input Fields (QsnReadInp), Read Immediate (QsnReadImm), Read Modified 
Fields (QsnReadMDT), Read Modified Alternate (QsnReadMDTAIt), or Read Modified Immediate 
Alternate (QsnReadMDTImmAIt) operation. You can use the Retrieve Length of Field Data in Buffer 
(QsnRtvFldDtaLen) API to retrieve the length of this data. Refer to the Read Input Fields (QsnReadInp) 


API for a description of the format of the data returned. 


To query the results from a QsnReadMDT, QsnReadMDTAIt, or QsnReadMDTImmAIt operation, you can 
also use the QsnRtvFldCnt and QsnRtvFldInf APIs. To query the result from any other input operations, 
use the QsnRtvDtaLen and QsnRtvDta APIs. 


Authorities and Locks 


None 


Required Parameter 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. The input buffer must 


be filled as a result of a QsnReadInp or QsnReadImm operation. 


Omissible Parameter Group 


Pointer to field data 
OUTPUT; PTR(SPP) 
The variable that contains the pointer to the field data when the QsnRtvFldDta API has completed. 
The value returned by this API is the null pointer if the buffer contains no field data. Otherwise, it 
is equivalent to adding 3 bytes to the address returned by QsnRtvDta API. (The cursor and AID key 


values account for the first 3 bytes of input data returned.) This parameter must be on a 16-byte 
boundary. 


Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Pointer to field data 
OUTPUT; PTR(SPP) 


This API returns the value for the pointer to field data parameter, or the null pointer otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPFA319 E No data in input buffer. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA31E E Required parameter &1 omitted. 

CPFA32E E Input data for query operation incorrect. 
CPFA32F E Buffer type incorrect. 

CPF3CI1F E Pointer is not on a 16 byte boundary. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
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Retrieve Read Information (QsnRtvReadinf) API 


Required Parameter Group: 


1 Input buffer handle Binary(4) 
2 Query result Char(*) 
3. Length of query result Binary(4) 


Omissible Parameter Group: 


4 Low-level environment Binary(4) 
handle 


5 Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Read Information (QsnRtvReadInf) API returns information about the input operation that 
filled the given input buffer. 


Authorities and Locks 


None 


Required Parameter Group 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that contains the results of the input operation. 
Query result 
OUTPUT; CHAR(*) 


The structure that contains the result of the query when the QsnRtvReadInf API has completed. The 
format of this structure is shown in Format of the Query Result. 


Length of query result 


INPUT; BINARY(4) 


The length of the query result parameter. The minimum value must be 8. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Query Result 


| Offset 
| Dec Hex /|Type Field 


[8 | 8 |CHAR@ [Reseed SCS 
a NAEYC [Number of fields in input buffer ~~ 
a 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


AID code for AID-associated read request. AID code corresponding to key pressed to service an 
AID-associated read request. The input buffer must be filled as a result of a QsnReadInp, QsnReadMDT, or 
QsnReadMDTAIt operation. If the input buffer is filled as a result of any other input operation, this field is 
set to X'00'. See AID-Generating Keys for a description of the possible values. 


Column location of cursor. Column location of cursor when the input operation was serviced. The input 
buffer must be filled as a result of a QsnReadInp, QsnReadMDT, QsnReadMDTAIt, QsnReadImm, or 
QsnReadMDTImmAlIt operation. If the input buffer is filled as a result of any other input operation, this 
field is set to -1. 


Number of bytes of data sent. Number of bytes of data sent from screen. If this value is larger than the 
number of bytes of input data, then truncation occurs on the input operation. 


Number of bytes of field data. Number of bytes of field data in input buffer. This does not include the 3 
bytes of header information (the cursor row and column, and the AID byte). The input buffer must be filled 
as a result of a QsnReadInp, QsnReadMDT, QsnReadMDTAIt, QsnReadImm, or QsnReadMDTImmAIlt 
operation. If the input buffer is filled as a result of any other input operation, this field is set to -1. 


Number of bytes of input data. Number of bytes of input data in input buffer. This includes header 
information such as row and column position. 


Number of fields in input buffer. Number of fields in input buffer. This does not include header 
information such as row and column position. The input buffer must be filled as a result of a 
QsnReadMDT, QsnReadMDTAIt, or QsnReadMDTImmAlIt operation. If the input buffer is filled as a 
result of any other input operation, or the input data format cannot be determined, this field is set to -1. 


Pointer to first byte of data. Pointer to first byte of data in input buffer. This includes header information 
such as row and column position. 


Pointer to first byte of field data. Pointer to first byte of field data in input buffer. This will be the first 
byte of data following the header information (the cursor row and column, and the AID byte). If the buffer 
does not contain field data, this field is set to the null pointer. 


Reserved. An ignored field. 


Row location of cursor. Row location of cursor when the input operation was serviced. The input buffer 
must be filled as a result of a QsnReadInp, QsnReadMDT, QsnReadMDTAIt, QsnReadImm, or 
QsnReadMDTImmAlt operation. If the input buffer is filled as a result of any other input operation, this 
field is set to -1. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CIF E 
CPF3C24 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA319 E 
CPFA31E E 
CPFA320 E 
CPFA32F E 
CPFA331 E 
CPFA334 E 
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Error Message Text 

Severe error while addressing parameter list. 
Pointer is not on a 16 byte boundary. 
Length of the receiver variable is not valid. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
No data in input buffer. 

Required parameter &1 omitted. 

Pointer parameter is null. 

Buffer type incorrect. 

Buffer handle incorrect. 


Low level environment handle incorrect. 
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Screen Input APIs 


The screen input APIs allow you to read data and other information from the screen. This includes field 
data, screen attributes, and the cursor address. The screen-input interfaces correspond, either directly or 
indirectly, to the 5250 data stream read commands. 


The screen input APIs are: 


Get AID (QsnGetAID) waits for an AID-generating key to be pressed. 


Get Cursor Address (QsnGetCsrAdr) gets the current cursor address. 


Get Cursor Address with AID (QsnGetCsrAdrAID) gets the current cursor address after an 
AID-generating key is pressed. 


Put Input Command (QsnPutInpCmd) issues a supplied read command. 


Read from Invited Device (QsnReadInvited) performs a read from invited device on a display that 
has already been invited. 


Read Immediate (QsnReadImm) reads the contents of all input fields on the display without 
requiring an AID key to be pressed. 


Read Input Fields (QsnReadInp) reads the contents of all input fields on the display requiring an 
AID key to be pressed. 


Read Modified Alternate (QsnReadMDTAIt) reads the contents of all modified fields on the 
display, alternate form, requiring an AID key to be pressed. 

Read Modified Fields (QsnReadMDT) reads the contents of all modified fields requiring an AID 
key to be pressed. 


Read Modified Immediate Alternate (QsnReadMDTImmAIt) reads the contents of all modified 
fields on the display, alternate form, without requiring an AID key to be pressed. 


Read Screen (QsnReadScr) reads the contents of the screen without requiring an AID key to be 
pressed. 


Top | Dynamic Screen Manager APIs | APIs by category 


Get AID (QsnGetAID) API 


Omissible Parameter Group: 


AID code Char(1) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value 


AID code Output Char(1) 


Service Default Program: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Get AID (QsnGetAID) API waits for an AID-generating key to be pressed. 
This command corresponds indirectly to the 5250 Read Input Fields command. Because the control 


characters specified on the underlying command are both X'00’, this operation will cause the cursor to move 
to the insert cursor position when the keyboard is unlocked. 


Authorities and Locks 


None 


Omissible Parameter Group 


AID code 
OUTPUT; CHAR(1) 


The variable that contains the AID code when the QsnRtvReadAID API has completed. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


AID code 


OUTPUT; CHAR(1) 


This API returns the value for the AID code parameter, X'00' if a general error occurs during 
processing. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA303 E 
CPFA304 E 
CPFA326 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Screen must be redrawn. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Get Cursor Address (QsnGetCsrAdr) API 


Omissible Parameter Group: 


Cursor row Binary(4) 
Cursor column Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Get Cursor Address (QsnGetCsrAdr) API returns the current cursor address, without requiring an 
AID-generating key to be pressed. Either the cursor row or cursor column parameter must be specified. If 
both of these parameters are omitted, a CPFA31E error occurs. 


This command corresponds indirectly to the 5250 Read Immediate command. 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Read Immediate (QsnReadImm) API. 


Omissible Parameter Group 


Cursor row 
OUTPUT; BINARY(4) 


The variable that contains the cursor row when the QsnGetCsrAdr API has completed. 
Cursor column 
OUTPUT; BINARY(4) 


The variable that contains the cursor column when the QsnGetCsrAdr API has completed. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPFA304 E 
CPF3CF2 E 
CPFA31E E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Data-stream error &1 reported for screen I/O operation. 
Error(s) occurred during running of &1 API. 

Required parameter &1 omitted. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Get Cursor Address with AID 
(QsnGetCsrAdrAlD) API 


Omissible Parameter Group: 


Cursor row Binary(4) 
Cursor column Binary(4) 
AID code Char(1) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Public Default Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Get Cursor Address with AID (QsnGetCsrAdrAID API returns the cursor address after an 
AID-generating key is pressed. Either the cursor row or the cursor column parameter must be specified. If 
both of these parameters are omitted, a CPFA31E error occurs. 


This command corresponds indirectly to the 5250 Read Input Fields command. Because the control 


characters specified on the underlying command are both X'00’, this operation may cause the cursor to 
move to the default, or insert cursor, position when the keyboard is unlocked. 


Authorities and Locks 


None 


Omissible Parameter Group 


Cursor row 
OUTPUT; BINARY(4) 


The variable that contains the cursor row when the QsnGetCsrAdrAID API has completed. 
Cursor column 
OUTPUT; BINARY(4) 


The variable that contains the cursor column when the QsnGetCsrAdrAID API has completed. 


AID code 


OUTPUT; CHAR(1) 


The variable that contains the AID code when the QsnGetCsrAdrAID API has completed. 
Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 


value of zero, the default low-level environment is used. 


Error code 


1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA304 E 
CPFA305 E 
CPFA31E E 
CPFA326 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 
Required parameter &1 omitted. 

Screen must be redrawn. 

Buffer handle incorrect. 

Low level environment handle incorrect. 
Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Put Input Command (QsnPutinpCmd) API 


Required Parameter: 
1 Command 
Omissible Parameter Group: 


Command data Input Char(*) 

Command data length Input Binary(4) 
Number of data bytes read Output Binary(4) 
Input buffer handle Input Binary(4) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code 1/O Char(*) 


Returned Value: 


Number of data bytes read Output Binary(4) 


Public Default Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Put Input Command (QsnPutInpCmd) API is used to issue data stream input commands that are not 
directly supported through a DSM API. An Escape (X'04') character is inserted in the stream directly before 
the command itself for both direct and indirect operations. 


You must use this operation to issue an input command that is not directly supported by DSM as this will 
cause the appropriate underlying screen I/O operation to occur in order to retrieve input. You cannot, for 
example, use the Put Output Command (QsnPutOutCmd) API to issue an input command because no input 
data will be requested by the underlying DSM screen I/O operation. 


The following command buffer handle and input buffer handle combinations are valid. 
e The command buffer handle is specified with a nonzero value. The input buffer handle is omitted 
or specified with a zero value. 
This is an indirect operation. The command is stored in the command buffer without an I/O 
operation taking place. 
e The command buffer handle is omitted or specified with a zero value. The input buffer handle is 


specified with a nonzero value. 


This is a direct operation. The input operation is issued to the screen, and the resulting input data is 
stored in the input buffer. 


e Both a command buffer handle and an input buffer handle are specified with nonzero values. 


This is a direct operation. The input operation is appended to the command stream given by the 
command buffer, and the entire command stream is written to the display. The resulting input data 
is stored in the input buffer. The contents of the command buffer are not affected by this operation. 
That is, the input operation is not stored in the command buffer. 


This operation corresponds to an Escape character followed by the specified command. 


Authorities and Locks 


None 


Required Parameter 


Command 
INPUT; CHAR(1) 
The 1-byte character code for the input command to be issued. For example, to issue a Save Partial 


Screen command, the command data should contain X'03' and the command data will contain the 
dimensions of the partial screen to be saved. 


Omissible Parameter Group 


Command data 
INPUT; CHAR(*) 


The data for the command to be issued. 
Command data length 
INPUT; BINARY(4) 


The length of the command data parameter. 
Number of data bytes read 
OUTPUT; BINARY(4) 
The variable that contains the number of data bytes returned after the QsnPutInpCmd API has 


completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 
A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. 
Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Number of data bytes read 
OUTPUT; BINARY(4) 


This API returns the value for the number of data bytes read parameter if a direct operation was 
specified, or -1 if an error occurs during processing. If this is an indirect operation, this API returns 
zero if successful, or -1 if there was a general failure. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA313 E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Command buffer already contains an input operation. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read from Invited Device (QsnReadInvited) API 


Required Parameter Group: 


1 Input buffer handle Binary(4) 


Omissible Parameter Group: 


Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Return code Binary(4) 
Error code Char(**) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


The Read from Invited Device (QsnReadInvited) API issues a read from invited device operation. Data will 
be returned in the format corresponding to the read command used. 


If the command buffer handle is specified and there is data to be sent in the command buffer, a QsnPutBuf 
will be issued to send the data to the screen. If no read command is in the command buffer, a read MDT 
command will be added to the data stream. Then the read from invited device will be issued. 


The input buffer handle parameter must be specified. 


See the appropriate read API for information on the format of the data returned. 


Authorities and Locks 


None 


Restrictions 


The invite active flag must be on in the low level environment description. 


An error will be issued if the command buffer is empty, or not specified, and no other write has been done 
with the invite active flag on in the low level environment description. 


Required Parameter Group 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to find the read command. 
If no read command is found in the specified command buffer, a read MDT with null control 
characters will be added to the data stream. This is the equivalent of calling the QsnReadMDT API. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Return code 
OUTPUT; BINARY(4) 
A return code indicating the result of the operation. The value returned will be 0 if the operation 


was successful, -1 if there was a general failure, and -2 if the operation was a read from invited 
device which timed out. 


Check the WAITRCD parameter on the display file specified in the low level environment 
description, to determine the time out value. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 
Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, -1 if there was a general failure, and -2 if the operation was a read from invited 
device which timed out. 


Check the WAITRCD parameter on the display file specified in the low level environment 


description, to determine the time out value. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA304 E 
CPFA305 E 
CPFA309 E 
CPFA31E E 
CPFA326 E 
CPFA327 E 
CPFA32F E 
CPFA331 E 
CPFA334 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Invalid cursor position in command buffer. 
Required parameter &1 omitted. 

Screen must be redrawn. 

Low level environment description value incorrect. 
Buffer type incorrect. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Immediate (QsnReadimm) API 


Omissible Parameter Group: 


Number of field data bytes Binary(4) 
read 


Input buffer handle Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Number of field data bytes Binary(4) 
read 


Public Default Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Read Immediate (QsnReadImm) API reads the contents of all input fields on the display without 
requiring an AID key to be pressed. The command buffer handle or input buffer handle parameter must be 
specified as described in Put Input Command (QsnPutInpCmd) API. 


The information returned depends on the condition of the master MDT bit. (See Modified Data Tag (MDT) 
Bit.) If the bit is not set, the input returned consists of the cursor address and an AID code only. If the bit is 


set, the input returned also includes the field data in the data portion of the input buffer. In each case, the 
returned cursor address indicates the current location of the cursor and an AID code of X'00'. The format of 
the field data returned is the same as that for the Read Input Fields (QsnReadInp) API. 


This command corresponds directly to the 5250 Read Immediate command. 


Authorities and Locks 


None 


Restrictions 


This command must be the last command in the command buffer. A CPFA305 error is issued if there is a 
subsequent attempt to add another command to the specified command buffer after this command. 


Omissible Parameter Group 


Number of field data bytes read 
OUTPUT; BINARY(4) 


The variable that contains the number of field data bytes returned after the QsnReadImm API has 
completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Number of field data bytes read 
OUTPUT; BINARY(4) 


This API returns the value for the number of field data bytes read parameter if a direct operation 
was specified, or -1 if an error occurs during processing. If this is an indirect operation, this API 
returns zero if successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA304 E 
CPFA305 E 
CPFA309 E 
CPFA313 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Invalid cursor position in command buffer. 
Command buffer already contains an input operation. 
Buffer handle incorrect. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Input Fields (QsnReadiInp) API 


Required Parameter Group: 


1. Control character byte 1 
2 Control character byte 2 


Omissible Parameter Group: 


Number of field data bytes | Output Binary(4) 
read 


Input buffer handle Input Binary(4) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 
Error code V/O Char(*) 


Returned Value: 


Number of field data bytes Output Binary(4) 
read 


Public Default Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Read Input Fields (QsnReadInp) API reads the contents of all input fields on the display while 
requiring an AID-generating key to be pressed. The command buffer handle or input buffer handle 
parameter must be specified as described in Put Input Command (QsnPutInpCmd) API. The format of the 


data returned is: 


Field Data Field Data Field Data 
Cursor AID Code 
Address in 1 byte 
Row/Column 
FMT 
2 bytes 


The information returned depends on the condition of the master MDT bit (see Modified Data Tag (MDT) 
Bit) and the AID-generating key pressed. If the bit is not set, the input returned consists of the cursor 
address and an AID code only. If the bit is set, the input returned also includes the field data in the data 
portion of the input buffer. In either case, the returned cursor address indicates the location of the cursor 
when the AID-generating key was pressed and the AID code for the AID-generating key the operator used. 
See AID-Generating Keys for a description of the AID-generating character values. 


Field data is returned only when one of the following AID-generating keys is used: 


Roll Up 

Roll Down 

Enter/Auto Record Advance 

Auto Enter 

An unmasked command function key 


The field data, when returned, consists of the contents of all input fields as they appear on the display, 
unless resequencing has been specified. (See Resequencing.) Any attributes contained in a field are treated 


as data and returned as such. The attributes that start and end a field are not returned. These are considered 
to be outside the boundaries of the field. No field delimiters are added; data from each field is followed 
directly by the data from the next field. Data for nontransparent fields is formatted as follows: 


e All nulls (leading, embedded, or trailing) are converted to blanks. 
e If the specified field is a signed numeric field: 
oO. The last character of the field is stripped off. 


oO The last location of the field is checked for a negative sign. If detected, the zone portion of 
the second to last character of the field is changed to a X'D'. 


2The data returned for transparent or CCSID-capable fields is not edited. A transparent field is defined 
with a transparency field control word X'84yy' (see Set Field (QsnSetFld) API.) The QsnSetFldCC API 
creates CCSID-capable fields. Each field read is returned unedited with no intervening control information. 
If a field is both transparent and signed numeric, unpredictable results can occur in the field data. CDRA 
conversion may be peformed upon this data, see Limitations and Restrictions for further details.% 


This command corresponds directly to the 5250 Read Input Fields command. 


Restrictions 


This command cannot be issued if the control unit supports ideographic data types. A CPFA306 error will 
occur if an attempt is made to issue this command to a control unit that supports ideographic data types. 


Some control units, like those emulated by the Client Access program, do not support a control character 
associated with input commands. For such units, the control character specified would be ignored. A 
program could cause further actions to be suspended if, for example, the control character byte 2 specified 
to unlock the keyboard and this action was not specified elsewhere in the data stream. If the underlying 
control unit does not support a control character with input commands, you must specify the action to 
perform using the QsnWTD API. 


Authorities and Locks 


None 


Required Parameter Group 


Control character byte 1 
INPUT; CHAR(1) 
The operation for the display to perform after the read operation has been serviced. See Control 
Characters for a description of the control character values. 


Control character byte 2 
INPUT; CHAR(1) 


The operation for the display to perform after the read operation and control character byte 1 have 
been serviced. See Control Characters for a description of the control character values. 


Omissible Parameter Group 


Number of field data bytes read 
OUTPUT; BINARY(4) 


The variable that contains the number of field data bytes returned after the QsnReadInp API has 
completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Number of field data bytes read 
OUTPUT; BINARY(4) 


This API returns the value for the number of field data bytes read parameter if a direct operation 
was specified, or -1 if an error occurs during processing. If this is an indirect operation, this API 
returns zero if successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA309 E 
CPFA313 E 
CPFA31C E 
CPFA31E E 
CPFA326 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Invalid cursor position in command buffer. 
Command buffer already contains an input operation. 
Incorrect value for control character byte &1. 
Required parameter &1 omitted. 

Screen must be redrawn. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Modified Alternate (QsnReadMDTAIt) API 


Required Parameter Group: 


1 Control character byte 1 
2 Control character byte 1 


Omissible Parameter Group: 


Field count Output Binary(4) 
Input buffer handle Input Binary(4) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 
Error code V/O Char(*) 


Returned Value: 


Field count Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Read Modified Alternate (QsnReadMDTAIt) API reads the contents of all modified fields on the 
screen, alternate form, requiring an AID-generating key to be pressed. The QsnReadMDTAIt API is 
functionally equivalent to the QsnReadMDT API with the following exceptions: 


e Leading and embedded nulls within the fields remain nulls. However, trailing nulls are stripped off. 
e For fields consisting entirely of nulls, but with their MDT bit on, only the field's address is 
returned. 


See Read Modified Fields (QsnReadMDT) API for details. 


This command corresponds directly to the 5250 Read MDT Alternate command. 


Authorities and Locks 


None 


Restrictions 


This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue 
this command to a control unit that does not support it. 


Some control units, like those emulated by the Client Access program, do not support a control character 
associated with input commands. For such units, the control character specified would be ignored. A 
program could cause further actions to be suspended if, for example, the control character byte 2 specified 
to unlock the keyboard and this action was not specified elsewhere in the data stream. If the underlying 
control unit does not support a control character with input commands, you must specify the action to 
perform using the QsnWTD API. 


Required Parameter Group 


Control character byte 1 
INPUT; CHAR(1) 
The operation for the display to perform after the read operation has been serviced. See Control 
Characters for a description of the control character values. 


Control character byte 2 
INPUT; CHAR(1) 


The operation for the display to perform after the read operation and control character byte 1 have 
been serviced. See Control Characters for a description of the control character values. 


Omissible Parameter Group 


Field count 
OUTPUT; BINARY(4) 


The variable that will contain the number of input fields read after the QsnReadMDTAIt API has 
completed, if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 
Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Field count 


OUTPUT; BINARY(4) 


Returns the value for the field count parameter if a direct operation was specified or -1 if an error 
occurs during processing. If this is an indirect operation, returns zero if successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA304 E 
CPFA305 E 
CPFA306 E 
CPFA309 E 
CPFA313 E 
CPFA31C E 
CPFA31E E 
CPFA326 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Command not supported by current device. 

Invalid cursor position in command buffer. 
Command buffer already contains an input operation. 
Incorrect value for control character byte &1. 
Required parameter &1 omitted. 

Screen must be redrawn. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Modified Fields (QsnReadMDT) API 


Required Parameter Group: 


1. Control character byte 1 
2 Control character byte 2 


Omissible Parameter Group: 


Field count Output Binary(4) 
Input buffer handle Input Binary(4) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 
Error code V/O Char(*) 


Returned Value: 


Field count Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Read Modified Fields (QsnReadMDT) API reads the contents of all modified fields on the screen 
requiring an AID-generating key to be pressed. The command buffer handle or input buffer handle 
parameter must be specified as described in Put Input Command (QsnPutInpCmd) API. See Control 


Characters for a description of the control character values. The format of the data returned is: 


Field Field 
Cursor AID Code} SBA Data| SBA Field Data 
Row/ Column} 1 byte |X'11'|Row/ Column X'11' |Row/ Column 
2 bytes 2 bytes 


ae 


The field data returned for transparent fields and CCSID-capable fields (created with QsnSetFldCC) 
includes an additional order and a length: 


Field Data 


Inbound Length of Transparent 


data 
Data order data or data in 
X'10' 2 bytes Field CCSID 


% 


The information returned depends on the state of the MDT bit for each field (see Modified Data Tag (MDT) 
Bit) and the AID-generating key used. If no bits are set, the input returned consists of the cursor address 


and an AID code only. If at least one bit is set, the input may also include field data. In each case, the 
returned cursor address indicates the location of the cursor when the AID-generating key was pressed and 
the AID code for the AID-generating key the operator used. 


Field data is returned only when one of the following AID-generating keys is used: 
Roll Up 
Roll Down 
Enter/Auto Record Advance 
An unmasked command function key 


The field data, when returned, consists of the row and column address and the contents of each field that 
has an MDT bit on as they appear on the display, unless resequencing has been specified. (See 
Resequencing.) The input buffer query routines Retrieve Number of Fields Read (QsnRtvFldCnt) API and 
Retrieve Field Information (QsnRtvFldInf) API can be used to retrieve the value for each field. (To 
interpret the data directly, QsnRtvDta can be used to obtain a pointer for the data portion of the input 
buffer. The first data byte will be the SBA order for the first field as defined in the 5250 data stream 
documentation. ) 


Data for nontransparent fields is formatted as follows: 


e Leading and embedded nulls within the field are translated to blanks, and trailing nulls are stripped 
off. Only the field's address is returned for fields whose MDT bit is on but which consist entirely of 
nulls. 


e If the specified field is a signed numeric field: 


oO The last character of the field is stripped off unless it was previously stripped because it 
was null. 


oO The last location of the field is checked for a negative sign. If detected, the zone portion of 
the second to last character of the field is changed to a X'D’. 


ao 


If the field is a transparent or CCSID-capable field, no formatting is performed. 


If a field is both transparent and signed numeric, unpredictable results can occur in the field data. CDRA 
conversion may be peformed upon this data, see Limitations and Restrictions for further details. 


= 
This command corresponds directly to the 5250 Read MDT Fields command. 


Restrictions 


Some control units, like those emulated by the Client Access program, do not support a control character 
associated with input commands. For such units, the control character specified would be ignored. A 
program could cause further actions to be suspended if, for example, the control character byte 2 specified 
to unlock the keyboard and this action was not specified elsewhere in the data stream. If the underlying 
control unit does not support a control character with input commands, you must specify the action to 
perform using the QsnWTD API. 


Authorities and Locks 


None 


Required Parameter Group 


Control character byte 1 
INPUT; CHAR(1) 
The operation for the display to perform after the read operation has been serviced. See Control 
Characters or a description of the control character values. 


Control character byte 2 
INPUT; CHAR(1) 


The operation for the display to perform after the read operation and control character byte 1 have 
been serviced. See Control Characters for a description of the control character values. 


Omissible Parameter Group 


Field count 
OUTPUT; BINARY(4) 


The variable that contains the number of input fields read after the QsnReadMDT API has 
completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Field count 


OUTPUT; BINARY(4) 


This API returns the value for the field count parameter if a direct operation was specified, or -1 if 
an error occurs during processing. If this is an indirect operation, this API returns zero if successful, 
or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA304 E 
CPFA305 E 
CPFA309 E 
CPFA313 E 
CPFA31C E 
CPFA31E E 
CPFA326 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Invalid cursor position in command buffer. 
Command buffer already contains an input operation. 
Incorrect value for control character byte &1. 
Required parameter &1 omitted. 

Screen must be redrawn. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Modified Immediate Alternate 
(QsnReadMDTImmaAIlt) API 


Omissible Parameter Group: 


Field count Binary(4) 
Input buffer handle Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Field count Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Read Modified Immediate Alternate (QsnReadMDTImmA It) API reads the contents of all modified 
fields on the display without requiring an AID-generating key to be pressed. Processing for this API is the 
same as for the Read Immediate (QsnReadImm) API, except that data is returned only for those fields that 
have the MDT bit on. The format of the data returned is the same as for the Read Modified Alternate 
(QsnReadMDTAIt) API. 


See Read Immediate (QsnReadImm) API and Read Modified Alternate (QsnReadMDTAIt) API for details. 


This command corresponds directly to the 5250 Read MDT Immediate Alternate command. 


Restrictions 


This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue 
this command to a control unit that does not support it. 


Authorities and Locks 


None 


Omissible Parameter Group 


Field count 
OUTPUT; BINARY(4) 


The variable that contains the number of input fields read after the QsnReadMDTImmAlIt API has 
completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Field count 
OUTPUT; BINARY(4) 


This API returns the value for the field count parameter if a direct operation was specified, or -1 if 
an error occurs during processing. If this is an indirect operation, this API returns zero if successful, 
or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA304 E 
CPFA305 E 
CPFA306 E 
CPFA309 E 
CPFA313 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Command not supported by current device. 

Invalid cursor position in command buffer. 
Command buffer already contains an input operation. 
Buffer handle incorrect. 

Low level environment handle incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Read Screen (QsnReadScr) API 


Omissible Parameter Group: 


Number of data bytes read Output Binary(4) 
Input buffer handle Input Binary(4) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code 1V/O Char(*) 


Returned Value: 


Number of data bytes read Output Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Read Screen (QsnReadScr) API reads the contents of the entire screen without requiring an 
AID-generating key to be pressed. The command buffer handle or input buffer handle parameter must be 
specified as described in Put Input Command (QsnPutInpCmd) API. 


The data returned consists of the contents of the entire display, including the attributes. No formatting or 
conversion is done. The data will be available in the data portion of the input buffer. The result of this 
operation can be queried using the Retrieve Length of Data in Input Buffer (QsnRtvDtaLen) API and the 


Retrieve Pointer to Data in Input Buffer (QsnRtvDta) API. 


This command corresponds directly to the 5250 Read Screen command. 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Read Immediate (QsnReadImm) API. In addition, this command 


cannot be issued if the control unit supports ideographic data types. A CPFA306 error occurs if an attempt 
is made to issue this command to a control unit that supports ideographic data types. 


Omissible Parameter Group 


Number of data bytes read 
OUTPUT; BINARY(4) 


The variable that contains the number of data bytes returned after the QsnReadScr API has 
completed if a direct operation is specified. The parameter is not modified for an indirect operation 
and the value remains unchanged from whatever was passed. 


Input buffer handle 
INPUT; BINARY(4) 


A handle for the input buffer that receives the result of the input operation if a direct operation is 
specified. The result can be queried using the input buffer query operations. See Retrieve Pointer to 


Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) 
API. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. 
Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Number of data bytes read 
OUTPUT; BINARY(4) 


This API returns the value for the number of data bytes read parameter if a direct operation was 
specified, or -1 if an error occurs during processing. If this is an indirect operation, this API returns 
zero if successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E 
CPFA301 E 
CPFA302 E 
CPFA304 E 
CPFA305 E 
CPFA309 E 
CPFA313 E 
CPFA331 E 
CPFA334 E 
CPFA343 E 


Error(s) occurred during running of &1 API. 
Command buffer is full. 

Command buffer or input buffer parameters required. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Invalid cursor position in command buffer. 

Command buffer already contains an input operation. 
Buffer handle incorrect. 

Low level environment handle incorrect. 


Output operation not done. 
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Screen Output APIs 


The screen output APIs are used to define fields and write data and other information to the screen. 


The screen output interfaces are: 


Delete Field ID Definition (QsnDItFldId) deletes a field ID definition. 
Generate a Beep (QsnBeep) generates a beep. 
Insert Cursor (QsnInsCsr) sets the insert cursor address. 


Pad between Two Screen Addresses (QsnWrtPadAdr) pads the screen with characters between two 
points. 


Pad for N Positions (QsnWrtPad) pads the screen for a specified number of characters. 


Put Output Command (QsnPutOutCmd) writes a data stream command. 
Set Cursor Address (QsnSetCsrAdr) sets the position of the cursor on the screen. 


Set Error State (QsnSetErr) places the keyboard into prehelp error state and optionally places a 
string on the error line with cursor positioning support. 
Set Field (QsnSetFld) defines an input field on the screen at a given row and column. 


Set Field with CCSID (QsnSetFldCC) defines a CCSID-capable input field on the screen at the 
given row and column.*& 


Set Output Address (QsnSetOutAdr) sets the current display address. 


Write Data (QsnWrtDta) writes data to the display at a given row and column with standard 
attributes. 


2Write Data with CCSID (QsnWrtDtaCC) writes data to the display at a given row and column 
using standard attributes.*& 


Write Structured Field Major (QsnWrtSFMaj) writes the major structure of a structured field. 
Write Structured Field Minor (QsnWrtSFMin) writes the minor structure of a structured field. 
Write to Display (QsnWTD) issues a Write to Display command. 


Write Transparent Data (QsnWrtTDta) writes transparent data to the display at a given row and 
column. 
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Delete Field ID Definition (QsnDItFldld) API 


Required Parameter: 
1 Field ID Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Delete Field ID Definition (QsnDItFldId) API deletes a field ID definition. The screen appearance, 
including the fields defined on the screen, are not affected by this command. 


Authorities and Locks 


None 


Required Parameter 


Field ID 
INPUT; BINARY(4) 


The ID for the field definition to be deleted. Subsequent references to this field ID result in a 
CPFA33C error. This parameter must be specified with a nonzero valid field value. 


Omissible Parameter 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA33C E Undefined field ID &1. 
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Generate a Beep (QsnBeep) API 


Omissible Parameter Group: 


Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Generate a Beep (QsnBeep) API generates a beep. The display address is not affected by this 
command. 


This command corresponds directly to the 5250 Write to Display (WTD) command with control character 1 


equal to X'00' and control character 2 equal to X'04". If this is an indirect operation, this API issues a new 
WTD command to the command buffer. 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API (see Restrictions). 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the beep is generated immediately. Otherwise, this is an 
indirect operation and the command is stored in the command buffer without an I/O operation 
taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 

CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
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Insert Cursor (QsninsCsr) API 


Omissible Parameter Group: 


Field ID Binary(4) 
Cursor row Binary(4) 
Cursor column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Insert Cursor (QsnInsCsr) API sets the insert-cursor address. The insert-cursor address specifies the 
home-cursor address. (The position of the cursor when the host system unlocks the keyboard and the 
display station operator presses the Home key.) The display address is not affected by this command if this 
is an indirect operation and the target command buffer contains an active Write to Display (WTD) 
command. Otherwise, a WTD command is inserted that resets the display address to row 1 column 1. 


If bit 1 of the associated Write to Display command is set to 0 (which is the default), the cursor will be 
moved on the screen when the QsnInsCsr API is called. To prevent the cursor from being moved, the 
control character byte 2 bit should be set to 1 and the Write to Display (QsnWTD) operation should be 
explicitly issued to a command buffer used by the QsnInsCsr API. 


This command corresponds indirectly to the 5250 Write to Display (WTD) command with an Insert Cursor 
order. (For an indirect operation, a WTD is placed in the command buffer only if one does not already exist 
in that buffer.) 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API. 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. Either the field ID or the row and 
column parameters must be specified. 


Cursor row 
INPUT; BINARY(4) 


The row at which to position the insert cursor. The row parameter must refer to a row no greater 
than the current screen or window mode height (if window mode is enabled). The actual screen row 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
row location of the top window border (0 for full screen) if offset is positive, or the row location of 
the bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is 
the row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


Cursor column 
INPUT; BINARY(4) 


The column at which to position the insert cursor. The column parameter must refer to a column no 
greater than the current screen or window mode width (if window mode is on). The actual screen 
column used for a screen I/O operation is calculated using the formula base+offset=actual. The 
base is the column location of the left window border (0 for full screen) if offset is positive, or the 
column location of the center window border (screen width plus 1 for full screen) if offset is 
negative. The offset is the column parameter value specified, and actual is the actual screen column 
to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the insert cursor is positioned at the specified location 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
I/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA33C E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Undefined field ID &1. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Pad between Two Screen Addresses 
(QsnWrtPadAdr) API 


Required Parameter Group: 


1 Pad character Char(1) 
2 Torow Binary(4) 
3. Tocolumn Binary(4) 


Omissible Parameter Group: 


From row Binary(4) 
From column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Pad between Two Screen Addresses (QsnWrtPadAdr) API pads the display repeatedly with a selected 
character between two positions on the screen. The current display address is set to the position given by 
the to-row and to-column values plus one. Padding may occur outside the logical window area defined by 
the low-level environment window mode setting. 


This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer 
Address order (if the from row and from column parameters are specified) and a Repeat to Address order. 


(For an indirect operation, a WTD is placed in the command buffer only if one does not already exist in that 
buffer.) 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API. 


Required Parameter Group 


Pad character 
INPUT; CHAR(1) 


The character to pad the screen with. 
To row 
INPUT; BINARY(4) 


The row at which to write the last pad character. If the position to pad to is less than the position to 
pad from, a CPFA31B error is issued. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


To column 
INPUT; BINARY(4) 


The column at which to write the last pad character. The column parameter must refer to a column 
no greater than the current screen or window mode width (if window mode is on). The actual 
screen column used for a screen I/O operation is calculated using the formula base+offset=actual. 
The base is the column location of the left window border (0 for full screen) if offset is positive, or 
the column location of the center window border (screen width plus 1 for full screen) if offset is 
negative. The offset is the column parameter value specified, and actual is the actual screen column 
to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Omissible Parameter Group 


From row 
INPUT; BINARY(4) 


The row at which to write the first pad character. The row parameter must refer to a row no greater 
than the current screen or window mode height (if window mode is enabled). The actual screen row 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
row location of the top window border (0 for full screen) if offset is positive, or the row location of 
the bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is 
the row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


If both the from-row and from-column parameters are omitted, the pad characters are written 
starting at the current display address. If the command is a direct operation or the buffer specified 
does not contain a preceding output operation that sets the display address, the current display 
address is set to row 1, column 1, prior to writing the pad characters. Both the from-row and 


from-column parameters must be specified, or both parameters must be omitted. 


From column 


INPUT; BINARY(4) 


The column at which to write the first pad character. The column parameter must refer to a column 
no greater than the current screen or window mode width (if window mode is on). The actual 
screen column used for a screen I/O operation is calculated using the formula base+offset=actual. 
The base is the column location of the left window border (0 for full screen) if offset is positive, or 
the column location of the center window border (screen width plus 1 for full screen) if offset is 
negative. The offset is the column parameter value specified, and actual is the actual screen column 


to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the screen is padded with the character specified 
between the positions specified inclusively. Otherwise, this is an indirect operation and the 
command is stored in the command buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 


value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA304 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 


Data-stream error &1 reported for screen I/O operation. 


CPFA305 E 
CPFA307 E 
CPFA308 E 
CPFA31B E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Attempt to write data past end of display. 

From position &1, &2 greater than to position &3, &4. 
Attempt to write outside of window area. 

Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Pad for N Positions (QsnWrtPad) API 


Required Parameter Group: 


1 Pad character Char(1) 
2 Number of bytes Binary(4) 


Omissible Parameter Group: 


Field ID Binary(4) 
From row Binary(4) 
From column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Pad for N Positions (QsnWrtPad) API pads the display with the given pad character for the specified 
number of bytes. Padding starts at the row and column specified, or at the current display address if these 
parameters are omitted. To allow the QsnWrtPad operation to insert a group of characters without 
overwriting the ending screen attribute, the following conditions must be satisfied: 


e The operation is an indirect operation. 

e The row and column parameters are omitted. 

e The low-level environment description does not indicate that DBCS data is being used. 

e The previous command saved in the command buffer was a Write Data (QsnWrtDta) operation. 
If the row and column parameters are omitted and the command is either a direct operation or the buffer 


specified does not contain a preceding output operation that sets the display address, then the current 
display address is set to row 1, column 1, prior to writing the pad characters. 


If the from-row and from-column parameters are specified, this command corresponds indirectly to the 
5250 Write to Display (WTD) command with a Set Buffer Address order. (For an indirect operation, a 
WTD is placed in the command buffer only if one does not already exist in the buffer.) 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API. 


Required Parameter Group 


Pad character 


INPUT; CHAR(1) 


The pad character to pad the screen with. 


Number of bytes 


INPUT; BINARY(4) 


The number of bytes to pad the screen for. 


Omissible Parameter Group 


Field ID 


INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. If neither the field ID or row and 
column parameters are specified, the current display address is used. 


From row 


INPUT; BINARY(4) 


The row at which to write the first pad character. The row parameter must refer to a row no greater 
than the current screen or window mode height (if window mode is enabled). The actual screen row 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
row location of the top window border (0 for full screen) if offset is positive, or the row location of 
the bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is 
the row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


If both the from-row and from-column parameters are omitted, the pad characters are written 
starting at the current display address. If this is the case and the command is a direct operation, or 
the buffer specified does not contain a preceding output operation that sets the display address, the 
current display address is set to row 1, column 1, prior to writing the pad characters. Both the 
from-row and from-column parameters must be specified, or both parameters must be omitted. 


From column 


INPUT; BINARY(4) 


The column at which to write the first pad character. The column parameter must refer to a column 
no greater than the current screen or window mode width (if window mode is on). The actual 
screen column used for a screen I/O operation is calculated using the formula base+offset=actual. 
The base is the column location of the left window border (0 for full screen) if offset is positive, or 
the column location of the center window border (screen width plus 1 for full screen) if offset is 
negative. The offset is the column parameter value specified, and actual is the actual screen column 
to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the pad characters are written to the screen at the 


current display address. Otherwise, this is an indirect operation and the command is stored in the 
command buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPFA301 E Command buffer is full. 

CPFA303 E Error occurred for screen I/O operation. 

CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 


CPFA307 E Screen position &1, &2 outside of display or window area. 


CPFA308 E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Attempt to write data past end of display. 
Attempt to write outside of window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 
Low level environment handle incorrect. 
Screen address parameter error. 
Undefined field ID &1. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Put Output Command (QsnPutOutCmd) API 


Required Parameter Group: 
1 Command 
Omissible Parameter Group: 


Command data Char(**) 
Command Data Length Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(**) 
Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Put Output Command (QsnPutOutCmd) API is used to issue data stream commands that are not 
directly supported through a DSM API. An escape (X'04') character is inserted in the stream directly before 
the command itself for both direct and indirect operations. 


Note: The Write Data (QsnWrtDta) API should be used for issuing Write to Display command orders such 
as the Write Extended Attributes order. 


This operation corresponds to an escape character followed by the specified command. 


Authorities and Locks 


None 


Required Parameter 


Command 
INPUT; CHAR(1) 


The 1-byte character code for the output command to be issued. For example, to issue a Restore 


Partial Screen, the command data should contain X'13', the command data will contain the restore 
data length followed by the restore data, and the command data length will be 2 plus the restore 
data length. 


Omissible Parameter Group 


Command data 
INPUT; CHAR(*) 


The data for the command to be issued. 
Command data length 
INPUT; BINARY(4) 


The length of the command data parameter. If 0 is specified, the command data parameter is 
ignored. Otherwise, the command data parameter is required. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the command is sent to the display. If the command 
being sent is an input command, you must specify a command buffer and then use the Put 
Command Buffer and Perform Get (QsnPutGetBuf) API to issue the command and retrieve the 
resulting input. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 
Low level environment handle incorrect. 
Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Set Cursor Address (QsnSetCsrAdr) API 


Omissible Parameter Group: 


Field ID Binary(4) 
Cursor row Binary(4) 
Cursor column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Cursor Address (QsnSetCsrAdr) API sets the position of the cursor on the screen. The display 
address is not affected by this command if this is an indirect operation and the target command buffer 
contains an active Write to Display (WTD) command. Otherwise, a WTD command will be inserted that 
resets the display address to row 1 column 1. 


This command corresponds indirectly to the 5250 Write to Display command (WTD) with an Insert Cursor 
or Move Cursor order. (For an indirect operation, a WTD is placed in the command buffer only if one does 
not already exist in that buffer.) The Move Cursor order is used if the control unit supports it (based on the 
5250 Query command). Otherwise, the Insert Cursor order is used. 


If the Move Cursor order is supported, this API sets the cursor without modifying the home address and 
without regard to the state of the keyboard. Otherwise, the behavior is the same as that of the Insert Cursor 
(QsnInsCsr) API. 


If multiple QsnSetCsrAdr operations are applied to the same command buffer, only the last QsnSetCsrAdr 
operation is in effect. The last QsnSetCsrAdr or QsnInsCsr operation determines the cursor position. If the 
Move Cursor order is used, the QsnSetCsrAdr negates any previous QsnInsCsr commands in the command 
buffer, except for the last QsnInsCsr, which sets the home position. If the Insert Cursor order is used, it 
negates any previous QsnInsCsr operations. If the Move Cursor order is supported, you can set the home 
position and then move the cursor by issuing a QsnInsCsr first, followed by a QsnSetCsrAdr operation. 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API. 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. Either the field ID or the row and 
column parameters must be specified. 


Cursor row 
INPUT; BINARY(4) 


The row at which to position the cursor. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


Cursor column 
INPUT; BINARY(4) 


The column at which to position the cursor. The column parameter must refer to a column no 
greater than the current screen or window mode width (if window mode is on). The actual screen 
column used for a screen I/O operation is calculated using the formula base+offset=actual. The 
base is the column location of the left window border (0 for full screen) if offset is positive, or the 
column location of the center window border (screen width plus 1 for full screen) if offset is 
negative. The offset is the column parameter value specified, and actual is the actual screen column 
to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the cursor is positioned at the specified location 


immediately. Otherwise, this is an indirect operation and the command is stored in the command 
buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 


value of zero, the default low-level environment is used. 
Error code 
1V/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 


was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPFA301 E Command buffer is full. 

CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 

CPFA307 E Screen position &1, &2 outside of display or window area. 
CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 

CPFA334 E Low level environment handle incorrect. 

CPFA33C E Undefined field ID &1. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 

CPFA345 E The invite active flag is not valid. 
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Set Error State (QsnSetErr) API 


Omissible Parameter Group: 


Message Input Char(*) 

Message length Input Binary(4) 
Field ID Input Binary(4) 
Cursor row Input Binary(4) 
Cursor column Input Binary(4) 


Starting monochrome Input Char(1) 
attribute 


Ending monochrome attribute Input Char(1) 
Starting color attribute Input Char(1) 
Ending color attribute Input Char(1) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code V/O Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Error State (QsnSetErr) API places the keyboard into prehelp error state and optionally places a 
string on the error line. To place the keyboard in the prehelp error state, you must follow this API with an 
AID-associated read API such as QsnReadInp. 


Either the cursor or the message parameters must be specified to make the command valid. If neither of 
these are used, a CPFA305 error is issued. If a cursor position is specified, the cursor is moved immediately 


to the location given. This does not affect the cursor address set by the Insert Cursor (QsnInsCsr) API. 


When the operator presses the Help key (prehelp error state only) in response to the error condition, the 
message No help text is available is displayed. 


This command corresponds directly to the 5250 Write Error Code command. 


Authorities and Locks 


None 


Omissible Parameter Group 


Message 
INPUT; CHAR(*) 


The message to be displayed. This parameter is required if the message length parameter is 
specified as a nonzero value. The message data, including the screen attributes, must not exceed 
132 characters for devices that are in 27x132 mode, or 80 characters for all other devices. A 
CPFA310 error is issued if the message data is too long. 


Message length 
INPUT; BINARY(4) 


The number of bytes of message data to be displayed. 
Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. 


Cursor row 
INPUT; BINARY(4) 


The row at which to position the cursor when the message is displayed. The row parameter must 
refer to a row no greater than the current screen or window mode height (if window mode is 
enabled). The actual screen row used for a screen I/O operation is calculated using the formula 
base+offset=actual. The base is the row location of the top window border (0 for full screen) if 
offset is positive, or the row location of the bottom window border (screen height plus 1 for full 
screen) if offset is negative. The offset is the row parameter value specified, and actual is the actual 
screen row to be used. A CPFA307 error occurs if an incorrect row value is specified. 


If both the field ID and the row and column parameters are omitted, the cursor is not moved. The 
row and column parameters must be specified together, or both parameters must be omitted. 


Cursor column 
INPUT; BINARY(4) 


The column at which to position the cursor when the message is displayed. The column parameter 
must refer to a column no greater than the current screen or window mode width (if window mode 
is on). The actual screen column used for a screen I/O operation is calculated using the formula 
base+offset=actual. The base is the column location of the left window border (0 for full screen) if 
offset is positive, or the column location of the center window border (screen width plus 1 for full 
screen) if offset is negative. The offset is the column parameter value specified, and actual is the 
actual screen column to be used. A CPFA307 error occurs if an incorrect column value is specified. 


Starting monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. If this parameter is omitted or specified as 


X'00'" a starting attribute of high intensity blink is inserted. See Screen Attribute Characters for a 


description of the screen attribute values. The starting attribute is selected as for the QsnWrtDta 
API. 


Ending monochrome attribute 
INPUT; CHAR(1) 


The ending screen attribute for monochrome displays. If this parameter is omitted or specified as 
X'00'", an ending attribute of nondisplay is inserted. The ending attribute is selected as for the 
QsnWrtDta API. 


Starting color attribute 
INPUT; CHAR(1) 


The initial screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no initial attribute is written to the display for the data. 


Ending color attribute 
INPUT; CHAR(1) 


The ending screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no ending attribute is written to the display for the data. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the error state is entered, the cursor is moved to the 
specified position, and the message, if specified, is displayed. Otherwise, this is an indirect 
operation and the command is stored in the command buffer without an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA30D E 
CPFA30F E 
CPFA310 E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA33F E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Invalid screen attribute. 

Required parameter not specified. 

Error message data/screen attributes exceed display width. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Error occurred during data conversion. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Set Field (QsnSetFld) API 


Omissible Parameter Group: 


Field ID Binary(4) 
Field length Binary(4) 
Row Binary(4) 
Column Binary(4) 
Field format word (FFW) Char(2) 
Field control words (FCW) Char(*) 


Number of field control Binary(4) 
words 


Monochrome attribute Char(1) 
Color attribute Char(1) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Field (QsnSetFld) API defines an input field on the screen at the given row and column. The 
following occurs when this command is issued to the control unit as a direct operation or when the buffer 
containing the command is written out: 


e Any outstanding AID requests are cleared. 
e The keyboard is locked. 


e If there is an entry in the format table whose starting address is equal to the address for this field, 
then that entry is modified. The FFW of the existing entry is replaced by the new FFW and the 
previous screen starting attribute is overlaid with the new screen starting attribute. The ending 
screen attribute is not rewritten. All FCWs and the length parameter are ignored. See the 5250 data 
stream documentation for details. 


e If no entry can be found in the table for the field being defined, a new entry will be added to the 
end of the table. However, the address must be greater than the ending address of the field currently 
defined last in the format table or an error will occur. If the new entry is valid, it will contain the 
field's FFW, the optional FCWs, and the field's starting and ending address. An error will occur if 
an attempt is made to define too many fields on the screen (see the 5250 data stream documentation 


for details). 


The display address after this operation will be the starting field address minus 1 if row and column are 
specified as valid positive integers or if this is the first field specified within the current WTD command. 
Otherwise, the display address will be one position past the ending screen attribute. 


This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer 
Address order and a Start of Field order if the row and column parameters are specified. (For an indirect 
operation, a WTD is placed in the command buffer only if one does not already exist in that buffer.) 


Authorities and Locks 


None 


Restrictions 


The same restrictions apply as for the Write Data (QsnWrtDta) API, with the exception that the trailing 
field attribute can be written past the end of the screen. (It will be suppressed by the control unit.) 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID to be associated with this field. The value specified can be any nonzero integer value. 
For APIs that accept a field ID parameter, this value can be subsequently used instead of the row 
and column parameter to specify a screen address. If the given ID is already defined, this operation 
will redefine that field ID with the values specified. To remove a field ID definition, use the 
QsnDItFldId API. 


If a previously defined field ID is supplied and some or all of the parameters are omitted, the field 
is defined using the current field definition values for those omitted parameters. 


If this field is omitted or specified with a value of zero, then no field ID is associated with this field 
description. 


Field length 
INPUT; BINARY(4) 


The length of the field being defined. If no field ID is specified, the length must be a positive 
integer value greater than 1 for signed numeric fields and greater than 0 for all other field types. 
The entire field must fit on the display. If a field ID is specified with a nonzero value, the length 
may be 0, in which case a field will not be defined on the screen; however, this will associate the 
field definition with the specified field ID. 


Row 
INPUT; BINARY(4) 


The row at which to define the field. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 


a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


The starting field address will be the row and column locations given if both parameters are 
specified. Otherwise, it will be the current display address plus 1. If this is the case and the 
command is a direct operation, or the buffer specified does not contain a preceding output operation 
that sets the display address, the current display address is set to row 1, column 1, prior to writing 
the initial screen attribute and the field definition. The ending field address for this field is the 
starting field address plus the field length. 


If a field ID is supplied along with a row and column, the row and column parameters will be 
stored as specified. These parameters will be used as relative or actual screen positions on a 
subsequent operation, depending upon the window mode setting for the environment supplied with 
that operation. 


If a previously undefined field ID is supplied with this operation, the row and column parameters 
must be specified. Also, the row and column parameters must both be specified or omitted; one 
cannot be specified if the other is omitted. A CPFA307 error occurs if an incorrect cursor position 
is specified. On some devices, row and column can both be specified as 1, which will cause the 
field to be defined at row 1, column 1, with a screen attribute of normal (X'20’). If this is the case, 
then any initial screen attribute parameters specified are ignored. This is only supported by certain 
devices. Whether or not this is supported can be determined by the Query 5250 (QsnQry5250) API. 


Column 
INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the center window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Field format word (FFW) 
INPUT; CHAR(2) 


The field format word is a 2-byte value that controls the type of the field being defined. Table 6 


shows the field types, and the corresponding bit to be set for each type. To omit this parameter, 
specify X'00' in both characters of the parameter. You must specify this parameter to define an 
input field, and it is required if a field control word is specified. 


Field control words (FCW) 
INPUT; CHAR(*) 


An array of 2-byte field control words. The field control words are 2-byte values that request 
certain functions to be performed. Table 7 shows the valid field control word values, their function, 


and mnemonics for those values. 


a 


The 5250 CCSID-based I/O specific FCWs are not allowed (QsnSetFldCC must be used to create 


CCSID-capable fields). If the CCSID-based I/O CCSID or Maximum data length FCWs are given 
here, a CPFA332 will result. FCWs will not be exhaustivly checked to see if they are formatted 


correctly or to see if the function requested is valid for the current device. However, some FCWs 
are checked against the support provided by the device and a CPFA306 signaled if an 
incompatibility is found. Table 8 shows the display capablility and FCW combinations that are 


valid. 


Errors not found here may be detected and reported when the FCW is required during subsequent 
command and keystroke processing. See the 5250 data stream documentation for further details 
about the meaning and use of these functions. 


% 


Number of field control words 
INPUT; BINARY(4) 


The number of control words in the field control word array. Omitting this parameter or specifying 
it with a value of 0 indicates that no field control words are specified with the FCW parameter. If 
this parameter is specified with a nonzero value, the FCW parameter is required; if the FCW 
parameter is omitted, a CPFA31E error is issued. 


Monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. A screen attribute is required for defining a 
field on the screen; if this parameter is omitted and monochrome attributes are to be used, X'20' is 
assumed. The initial screen attribute is written one position to the left of the starting field address. 
The ending screen attribute (X'20') is supplied by the controller and written at the end-of-field 
address plus 1. 


The monochrome attribute and color attribute parameters consist of 1 byte that will be used as the 
screen attribute for a monochrome or a color display, respectively. One of these parameters will be 
selected based on the underlying display type, and the other will be discarded. See Screen Attribute 


Characters for a description of the screen attribute values. 


Color attribute 
INPUT; CHAR(1) 
The initial screen attribute for color displays. A screen attribute is required for defining a field on 


the screen; if this parameter is omitted and color attributes are to be used, X'20' is assumed. See 
Screen Attribute Characters for a description of the screen attribute values. 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the starting field address will be the supplied location. 


Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Field Format Word 


The following table shows the field types and the bits to set for each type for the field format word (FFW). 
Table 6. Field Format Words 


Field Type Bit To Mnemonic Description 
Set 
0-15 QSN_NO_FFW If bits 0 to 15 are set to 0, then 
no FFW is used. The field will 
be defined as an output field 
the Read Input Fields 
(QsnReadInp) API. 
0-1 The first two bits of a field 
format word must be 01. The 
mnemonic for every other 
field type includes this setting. 
Bypass 2 QSN_FFW_BYPASS If this bit is set, this is a 
bypass field and entries are 
not allowed in it. If the 
operator tries to enter 
something in this field, an 
error results. 


and its contents will not be 
Dup Enable 3 QSN_FFW_DUP If this bit is set, duplication is 
allowed in the field. The 
controller repeats X'1C' from 
the cursor position to the end 
of the field when the operator 
presses the Dup key; this 
shows on the display as an 
overstruck asterisk. 


returned by operations such as 


Modified data tag (MDT) 


4 QSN_FFW_MDT Setting this bit sets the 
modified data tag for this 
field. The field will then be 
read with the Read Modified 
Fields (QsnReadMDT) API 
(see Read Modified Fields 
(QsnReadMDT) APD) as if the 
operator had modified it. 


Field Shift/ Edit Bits 5-7 Mnemonic Description 
Specification 


Alphabetic shift 000 QSN_FFW_ALPHA_SHIFT The field accepts all 
characters. The shift keys are 
acknowledged. The characters 
on the lower symbol of each 
key are valid. 


Alphabetic only 001 QSN_FFW_ALPHA_ONLY The field accepts only 
characters A-Z (both 
uppercase and lowercase) plus 
the comma (,), period (.), 
minus (-), space, and DUP (if 
the DUP-enable bit is on in 
the associated Field Format 
Word (FFW)). Other 
characters cause operator 
errors. Some special 
characters are also acceptable 


(see the 5250 data stream 


documentation). 
Numeric shift QSN_FFW_NUM_SHIFT The field accepts all 
characters from all keys. 


Numeric only O11 QSN_FFW_NUM_ONLY The field accepts only 
characters 0-9 and the comma 
(,), period (.), minus (-), plus 
(+), space, and DUP (if the 
DUP-enable bit is on in the 
associated Field Format Word 
(FFW)). Other characters 


cause operator errors. 


The unit position of this field 
will carry the sign digit for the 
field. If the field is exited with 
the Field - key, the last 
character in the field will be 
'D' zoned, unless the last 
character in the field is a'+', 
'-",'\', '", or space, in which 
case an error will be posted. 

In a center-adjusted field, the 
field will be center-adjusted 
before any 'D' zoning or 
testing of the sign character is 
performed. When a negative 
field (from the Field - key) is 


returned, the units digit will 
have a 'D' zone. 


Katakana shift 100 QSN_FFW_KATA 


This is the same as the 
alphabetic shift except that the 
keyboard is placed in the 
Katakana shift on the Japan 
Katakana data entry, 
typewriter, and G keyboards. 
This reverses the order of the 
cursor direction with respect 
to the screen. If the display is 
in bidirectional mode, this 
changes the cursor direction 

to left to center; otherwise, it 
changes the cursor direction 

to center to left. 


The field allows keys 0-9 and 
DUP (if the DUP-enable bit is 
on in the associated Field 
Format Word (FFW)). 


This field will not accept any 
data keys from the keyboard. 
An operator error is posted if 
keystrokes are entered in this 
field. The operator may move 
the cursor into and out of this 
field similar to operation in 
any non-bypass input field 
(that is, Field Advance will 
position the cursor to the start 
of the field). 


101 QSN_FFW_DIGIT_ONLY 


110 QSN_FFW_IO 


This field can be used for 
input from feature devices 
such as a magnetic stripe 
reader of selector light pen 
while data input from the 
keyboard is excluded. 


The Field +, Field Exit, and 
Dup keys are valid for this 
field and performance is the 
same as that for any 
non-bypass input field. 


Signed Numeric 111 QSN_FFW_SIGNED_NUMERIC |The field allows keys 0-9 and 
DUP (if the DUP-enable bit is 
on in the associated Field 
Format Word (FFW)). Typing 
any other character will cause 


an operator error display. 


This field reserves the 
center-hand position for a sign 
display (- for negative and 
null for positive); therefore, 
the largest number of 
characters that can be entered 
into this field is one less than 
the field length. A signed 
numeric field less than 2 
characters long will cause an 
error to be flagged. 


No digit may be keyed into 
the centermost position; 
however, the cursor can be 
positioned there by using the 
cursor movement keys and 
then followed by the F+ or F- 
key. This allows changing the 
sign without affecting the rest 
of the field. 


If this field is not a mandatory 
fill or center-adjust field, it is 
still handled as if it were 
specified as a center-adjust 
blank fill field. If the Field - 
key is used to exit this field, 
the field will be 
center-adjusted and a negative 
sign placed in the centermost 
position of the field. The Field 
Exit or Field + key will insert 
a blank in the centermost 
position and center-adjust this 
field. 


Before this field is returned on 
an input operation, it is 
changed as follows: 


e If the centermost 
character is a negative 
sign, the zone of the 
low order digit is set 
toa X'D'. 

e Ifthe centermost 
character is not a 
negative sign, the low 
order digit is not 


changed. 


In either case, the centermost 
sign position is not sent to the 


host. 
Field Type Bit to Mnemonic Description 
| | Set | | 


Auto Enter QSN_FFW_AUTO_ENTER 


If this bit is set, this is an auto 
enter field. The auto enter 
function occurs only for valid 
Field Exit/Field +, Field -, and 
Dup exit keys, or if the last 
data character position is 
typed into the auto enter field. 
After any required 
center-adjust, mandatory fill, 
data duplicating, or check 
digit operations are 
successfully performed, the 
auto enter function causes the 
panel to be sent to the host as 
if the Enter key had been 
pressed. 


QSN_FFW_AUTO_FER If this bit is set, a nondata key 
must be typed to leave the 
field. When the last data 
character is typed into the last 
position of the field, the 
cursor will remain under the 
character and blink, signifying 
the controller is waiting for an 
exit key. Any nondata key 
will satisfy the exit 
requirement (including cursor 
movement or function keys). 


Field Exit Required 
If this bit is set, then 
regardless of the shift state of 
the typewriter keyboard, only 
the uppercase A-Z is entered 
into the field being typed (that 
is, if a lowercase a is typed, 
the uppercase A is entered). 
All other characters are 
unaffected. Certain characters 
on some typewriter keyboards 
also will be translated to 
uppercase (see the 5250 data 


Monocase 10 
stream documentation). 


Reserved 


QSN_FFW_AUTO_MONOCASE 


If this bit is set, the operator 
must enter something in the 
field before the controller 
allows the Enter key to be 
active. The controller 
recognizes the state of these 
fields by checking the MDT 
bit for the field. If the operator 
tries to bypass the field using 
a Field +, Field -, or Field 


QSN_FFW_ME 
Exit key, an error occurs. 


Center-Adjust/Mandatory | Bits i) ee | Description 
Fill 13-15 


iota ea! Ea Wee cola 
[Reserved ——— —(té‘*OO “f 
[Reserved 010 
[Reserved (ON ff 
[Reserved sf 


Center-adjust, zero fill 101 QSN_FFW_RA_ZERO All leftmost unoccupied 
positions of a field are filled 
with zero. Characters are 
center-adjusted and spaces are 
zero-filled. The fill character 
will appear on the display. 


center-adjust is only activated 
by keying the Field Exit, Field 
+, or Field - keys. The field is 
center-adjusted from the first 
non-null character to the left 
of the cursor when one of 
these keys is depressed. If a 
center-adjust field is left 
through cursor movement 
keys, the field will remain as 
is (not center-adjusted). 
center-adjust fields longer 
than 15 characters might 
cause a slow response that 
would result in a keyboard 
overrun. A center-adjust 
specified field has an implied 
field exit required function. 


The Dup key will fill a 
center-adjust field from the 
cursor to the end of the field 
with the Dup character 
(X‘1C’'), but the field will not 
be center-adjusted. After 
typing the first character into 
a center adjust field, but prior 
to exiting the field (using 
cursor movement or exit 


keys), the Enter key will 
cause an operator error to be 
posted; that is, Enter is invalid 
from an active center-adjust 
field. 


Center-adjust, blank fill 110 QSN_FFW_RA_ BLANK The field behavior is the same 
as for center-adjust, zero fill, 
but the fill character is blank 
instead of zero. 

111 QSN_FFW_MF Once any data has been 


entered into the field, the field 
must be completely filled 
before exiting it. Any attempt 
to leave an unfilled field 
causes an error. The cursor 
may pass into and out of a 
mandatory fill field as a result 
of cursor movement keys 
without fill-checking or error 
posting by the controller, as 
long as no data is entered into 
the field. 


The Dup key will fill the field 
from the cursor to the end of 
field with the Dup characters 
X'2C', and then the entire field 
will be checked for any nulls 
(an error is posted if a null is 
found). A mandatory fill field 
with nulls can be returned 
under the following 
conditions: 


1. The field was 
initialized with nulls 
and with the MDT bit 
on. 


2. The Erase Input, Field 
Exit, or Field + key is 
used from the first 
position of the field. 
The field is filled with 
nulls and the MDT bit 
is set on. 


The above fields, with no 
further entry, can be returned 
with all data as blanks on a 
Read Input Fields 
(QsnReadInp) operation or as 


Format of the Field Control Word 


The following table explains the valid field control words (FCW) for use with the QsnSetFld API. 


Table 7. Field Control Words 


[FCW Value Value [Mnemonic = [Mnemonic =—_—_—s[Desccription 

x' pow eee QSN_FCW_RESEQ Entry field resequencing (used in the Read Input 
Fields (QsnReadInp) and Read Modified Fields 
(QsnReadMDT) APIs, and so forth). The nn specifies 
the next entry field in the sequence (nn can be X'00! 
to X'80'). See Resequencing. 

[x’ 8101' [QSN N_FCW_MSR [Magnetic stripe reader entry field. 

x’ 8102' [QSN y_FCW_SLP [s elector light pen entry field. 


X'8103' QSN_FCW_MSR_SLP Magnetic stripe reader and selector light pen entry 
| | Pe 


[x'8106 == |QSN_FCW_SLP_SA [Selector light pen and selectable attention entry field. 
[x'8200" = [QSN_FCW_DBCS_ONLY [DBCS onlyentryfield. 
[x'8220" = [QSN_FCW_DBCS_PURE [DBCS Graphic DBCS entry field. 
[x'8240" ss [QSN_FCW_DBCS_EITHER [DBCS Eitherentryfield. = 


X'8280' or QSN_FCW_DBCS_OPEN or |DBCS open entry field. 
X'82C0' QSN_FCW_DBCS_OPEN_CO0O 


QSN_FCW_TRANSPARENT |Transparency entry field (used in the Read Input 
Fields (QsnReadInp) and Read Modified Fields 
(QsnReadMDT) APIs, and so forth). The ?? indicates 
that these values are ignored. 


X'8501' QSN_FCW_FET Forward edge trigger entry field. This provides the 
same function as Auto Enter specified in the FFW, 
except a unique AID is returned to the host when the 
field is exited. The state on the Auto Enter flag in the 
FFW is ignored. 


[x'8601' = [QSN_FCW_CONT_FIRST [Continued entry field firstsegment. 
[x'8602" = [QSN_FCW_CONT_LAST [Continued entry fieldlast segment. 
[x'8603' == = {QSN_FCW_CONT_MIDDLE Continued entry field middle segment. 
[X'88nn’ ss (QSN_FCW_CP———SCSCsCS Curr proogrression entry field. = 
[X'89nn’ = (QSN_FCW_HL————SOSCSHighlightedeentryfield@ 
[X'8Ann’ = [QSN_FCW_PDS-————SCSC*dointer device selection entry field. = 
[X'B140. ss (QSN_FCW_MOD11 —s[Self Check Modulus ll entry field. = 
[X'BIAO’ = [QSN_FCW_MOD10.— [Self Check Modulus 10 entry field. 


> 
Valid Field Control Word and Device Capability Combinations 


The following table explains the field control words (FCW) available for certain capabilities of the device. 
If one of the FCW values listed is given to QsnSetFld and the corresponding device capability is not 
supported, a CPFA306 will result. QsnSetFld, however, does not detect all invalid FCW combinations. See 


the Field control words (FCW) parameter for more information. 


See the QsnQry5250 API to determine the capablilities supported by the current device. 


Table 8. Valid Field Control Word and Device Capability Combinations 


Display 
capablility 


FCW Values required for 


FCW to be 
valid 
QSN_FCW_CONT_FIRST, ENPTUI 
QSN_FCW_CONT_MIDDLE, 
N_FCW_DBCS_ ONLY, 
QSN_FCW_DBCS_EITHER, DBCS 
QSN_FCW_DBCS_OPEN, 
= FCW_DBCS_OPEN_CO 
[QSN_FCW_DBCS_PURE DBCS_PURE Pure [Pure DBCS 


N_FCW_TRANSPARENT a 
Data 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPFA301 E Command buffer is full. 

CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 

a 

CPFA306 E Command not supported by current device. 

= 

CPFA307 E Screen position &1, &2 outside of display or window area. 
CPFA308 E Attempt to write data past end of display. 

CPFA30A E Field length &1 not valid. 

CPFA30B E Invalid starting address for field. 

CPFA30C E Maximum allowable number of fields exceeded. 
CPFA30D E Invalid screen attribute. 


CPFA30E E 
CPFA314 E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA332 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33D E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Invalid field format word. 

Memory allocation error. 

Attempt to write outside of window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Incorrect field control word. 

Parameter &1 not positive integer value. 
Low level environment handle incorrect. 
Screen address parameter error. 

Invalid screen attribute. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


»Set Field with CCSID (QsnSetFldCC) API 


Omissible Parameter Group: 


Field ID Binary(4) 
Field length Binary(4) 
Display Positions Binary(4) 
CCSID Binary(4) 
Row Binary(4) 
Column Binary(4) 
Field format word (FFW) Char(2) 
Field control words (FCW) Char(*) 
Number of field control words Binary(4) 
Monochrome attribute Char(1) 
Color attribute Char(1) 
Command buffer handle Binary(4) 
Low-level environment handle Binary(4) 
Error code Char(*) 


1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 


= Re Re 
WN 


Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Set Field with CCSID (QsnSetFldCC) API defines a CCSID-capable input field on the screen at the 
given row and column. The following occurs when this command is issued to the control unit as a direct 
operation or when the buffer containing the command is written out: 


e Any outstanding AID requests are cleared. 
e The keyboard is locked. 


e If there is an entry in the format table whose starting address is equal to the address for this field, 
then that entry is modified. The FFW of the existing entry is replaced by the new FFW and the 
previous screen starting attribute is overlaid with the new screen starting attribute. The ending 
screen attribute is not rewritten. All FCWs and the length parameter are ignored. See the 5250 data 
stream documentation for details. 


e If no entry can be found in the table for the field being defined, a new entry will be added to the 
end of the table. However, the address must be greater than the ending address of the field currently 
defined last in the format table or an error will occur. If the new entry is valid, it will contain the 
field's FFW, the optional FCWs, and the field's starting and ending address. An error will occur if 
an attempt is made to define too many fields on the screen (see the 5250 data stream documentation 


for details). 


The display address after this operation will be the starting field address minus 1 if row and column are 
specified as valid positive integers or if this is the first field specified within the current WTD command. 
Otherwise, the display address will be one position past the ending screen attribute. 


This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer 
Address order and a Start of Field order if the row and column parameters are specified. Special FC Ws 
inserted into the data stream by this API to make the field CCSID-capable. (For an indirect operation, a 
WTD is placed in the command buffer only if one does not already exist in that buffer.) 


Restrictions 


The same restrictions apply as for the Write Data with CCSID (QsnWrtDtaCC) API, with the exception that 
the trailing field attribute can be written past the end of the screen. (It will be suppressed by the control 
unit.) 


This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue 
this command to a control unit that does not support it. 


At this time, the CCSID given must have a unicode encoding scheme, otherwise a CPF3BDE will be 
signaled. 


Authorities and Locks 


None 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID to be associated with this field. The value specified can be any nonzero integer value. 
For APIs that accept a field ID parameter, this value can be subsequently used instead of the row 
and column parameter to specify a screen address. If the given ID is already defined, this operation 
will redefine that field ID with the values specified. To remove a field ID definition, use the 
QsnDItFldId API. 


If a previously defined field ID is supplied and some or all of the parameters are omitted, the field 
is defined using the current field definition values for those omitted parameters. 


If this field is omitted or specified with a value of zero, then no field ID is associated with this field 
description. 
Field length 
INPUT; BINARY(4) 
The number of bytes that this field being defined contains (a single character might be composed of 


multiple bytes). If no field ID is specified, the length must be a positive integer value greater than 1 
for signed numeric fields and greater than 0 for all other field types. The entire field must fit on the 


display. If a field ID is specified with a nonzero value, the length may be 0, in which case a field 
will not be defined on the screen; however, this will associate the field definition with the specified 
field ID. 


Display positions 


CCSID 


Row 


INPUT; BINARY(4) 


The number of positions on the display allowed for this field being defined (a single character may 
require more than one position on the display). 


If this parameter is not specified, the default is the number given by the field length parameter. 


INPUT; BINARY(4) 


The CCSID of the data that can be entered into this field. If the CCSID given is not supported by 
the device, a CPF3BDE is signaled. 


If this parameter is omitted (zero is passed in as the CCSID), and the field ID parameter was 
omitted or previously undefined, the job CCSID is used. If the job CCSID is 65535, the default job 
CCSID is used instead. 


INPUT; BINARY(4) 


The row at which to define the field. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


The starting field address will be the row and column locations given if both parameters are 
specified. Otherwise, it will be the current display address plus 1. If this is the case and the 
command is a direct operation, or the buffer specified does not contain a preceding output operation 
that sets the display address, the current display address is set to row 1, column 1, prior to writing 
the initial screen attribute and the field definition. The ending field address for this field is the 
starting field address plus the number of character positions for the field. 


If a field ID is supplied along with a row and column, the row and column parameters will be 
stored as specified. These parameters will be used as relative or actual screen positions on a 
subsequent operation, depending upon the window mode setting for the environment supplied with 
that operation. 


If a previously undefined field ID is supplied with this operation, the row and column parameters 
must be specified. Also, the row and column parameters must both be specified or omitted; one 
cannot be specified if the other is omitted. A CPFA307 error occurs if an incorrect cursor position 
is specified. On some devices, row and column can both be specified as 1, which will cause the 
field to be defined at row 1, column 1, with a screen attribute of normal (X'20’). If this is the case, 
then any initial screen attribute parameters specified are ignored. This is only supported by certain 
devices. Whether or not this is supported can be determined by the Query 5250 (QsnQry5250) API. 


Column 


INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 


used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the right window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Field format word (FFW) 
INPUT; CHAR(2) 


The field format word is a 2-byte value that controls the type of the field being defined. QsnSetFld 
Table 6 shows the field types, and the corresponding bit to be set for each type. To omit this 


parameter, specify X'00' in both characters of the parameter. You must specify this parameter to 
define an input field, and it is required if a field control word is specified. 


Field control words (FCW) 
INPUT; CHAR(*) 


An array of 2-byte field control words. The field control words are 2-byte values that request 
certain functions to be performed. Table 10 shows the valid field control word values, their 


function, and mnemonics for those values. 


Note: The 5250 CCSID-based I/O specific FCWs are not allowed, because they are implicitly 
added as part of the QsnSetFldCC operation. If the CCSID-based I/O CCSID or Maximum data 
length FCWs are given here, a CPFA332 will result. FCWs will not be exhaustivly checked to see 
if they are formatted correctly or to see if the function requested is valid for the current device. 
However, some FCWs are checked against the support provided by the device and a CPFA306 
signaled if an incompatibility is found. Table 11 shows the display capablility and FCW 
combinations that are valid. 


Errors not found here may be detected and reported when the FCW is required during subsequent 
command and keystroke processing. See the 5250 data stream documentation for further details 
about the meaning and use of these functions. 


Number of field control words 
INPUT; BINARY(4) 


The number of control words in the field control word array. Omitting this parameter or specifying 
it with a value of 0 indicates that no field control words are specified with the FCW parameter. If 
this parameter is specified with a nonzero value, the FCW parameter is required; if the FCW 
parameter is omitted, a CPFA31E error is issued. 


Monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. A screen attribute is required for defining a 
field on the screen; if this parameter is omitted and monochrome attributes are to be used, X'20' is 
assumed. The initial screen attribute is written one position to the left of the starting field address. 
The ending screen attribute (X'20') is supplied by the controller and written at the end-of-field 
address plus 1. 


The monochrome attribute and color attribute parameters consist of 1 byte that will be used as the 
screen attribute for a monochrome or a color display, respectively. One of these parameters will be 
selected based on the underlying display type, and the other will be discarded. See Screen Attribute 


Characters for a description of the screen attribute values. 


Color attribute 
INPUT; CHAR(1) 


The initial screen attribute for color displays. A screen attribute is required for defining a field on 
the screen; if this parameter is omitted and color attributes are to be used, X'20' is assumed. See 
Screen Attribute Characters for a description of the screen attribute values. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the starting field address will be the supplied location. 
Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Return Value 
Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Field Control Word 


The following table explains the valid field control words (FCW) for use with the QsnSetFldCC API. 
Field Control Words 


[FCW Value [Mnemonic Description 


X'80nn' QSN_FCW_RESEQ Entry field resequencing (used in the Read Input 
Fields (QsnReadInp) and Read Modified Fields 
(QsnReadMDT) APIs, and so forth). The nn specifies 
the next entry field in the sequence (nn can be X'00' to 
X'80'). See Resequencing. 


[x's 101' [QSN_FCW_MSR Magnetic stripe reader entry field. 
x's 102' |QSN_FCW_SLP Selector light pen entry field. 


X'8103' QSN_FCW_MSR_SLP Magnetic stripe reader and selector light pen entry 
| | field. 


x’ 106' |QSN_FCW_SLP_SA Selector light pen and selectable attention entry field. 


Forward edge trigger entry field. This provides the 
same function as Auto Enter specified in the FFW, 
except a unique AID is returned to the host when the 
field is exited. The state on the Auto Enter flag in the 


, 8501" . FCW_FET 
FFW is ignored. 

[x'8601' = [QSN_FCW_CONT_FIRST [Continued entry field first segment. 
[X'8602" ss [QSN_FCW_CONT_LAST [Continued entry field last segment. 
[x'8603' = [QSN_FCW_CONT_MIDDLE |Continued entry field middle segment. 
[X'88nn’ = [(QSN_FCW_CP ———SCsSCurrsor progressionentryfield- = 
[X'89nn’ = [QSN_FCW_HL————C~*=é‘CMXigh lighted entry field, = 
[X'8Ann’ = [(QSN_FCW_PDS_—————SSsé*(Poiintter device selection entry field. = 
[X'B140' = (QSN_FCW_MOD11_ —— [Self Check Modulus I] entry field. = 
[X'BIAO’ = [QSN_FCW_MOD10-—s‘[Self Check Modulus 10 entry field. 


Valid Field Control Word and Device Capability Combinations 


The following table explains the field control words (FCW) available for certain capabilities of the device. 
If one of the FCW values listed is given to QsnSetFIdCC and the corresponding device capability is not 
supported, a CPFA306 will result. QsnSetFldCC, however, does not detect all invalid FCW combinations. 
See the Field control words (FCW) parameter for more information. 


See the QsnQry5250 API to determine the capablilities supported by the current device. 
[Valid Field Control Word and Device Capability Combinations 


Display capablility required for 
| BOW values FCW to be valid 


QSN_FCW_CONT_FIRST, 
QSN_FCW_CONT_MIDDLE, 
QSN_FCW_CONT_LAST, 
QSN_FCW_CP, 
QSN_FCW_HL, 
QSN_FCW_PDS 


ENPTUI 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3BDE E CCSID &1 not supported by API. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 


CPFA301 E Command buffer is full. 


CPFA304 E 
CPFA305 E 
CPFA306 E 
CPFA307 E 
CPFA308 E 
CPFA30A E 
CPFA30B E 
CPFA30C E 
CPFA30D E 
CPFA30E E 
CPFA314 E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA332 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33D E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


4 


Data-stream error &1 reported for screen I/O operation. 


Cannot add operation to command buffer. 


Command not supported by current device. 


Screen position &1, &2 outside of display or window area. 


Attempt to write data past end of display. 
Field length &1 not valid. 


Invalid starting address for field. 


Maximum allowable number of fields exceeded. 


Invalid screen attribute. 

Invalid field format word. 

Memory allocation error. 

Attempt to write outside of window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Incorrect field control word. 

Parameter &1 not positive integer value. 
Low level environment handle incorrect. 
Screen address parameter error. 

Invalid screen attribute. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


API Introduced: V5R2 


Top | Dynamic Screen Manager APIs | APIs by category 


Set Output Address (QsnSetOutAdr) API 


Omissible Parameter Group: 


Field ID Binary(4) 
Row Binary(4) 
Column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Output Address (QsnSetOutAdr) API sets the current display address. Subsequent output 
operations that do not reset the display address use this address. If multiple Set Output Address 
(QsnSetOutAdr) operations are applied to the same command buffer, only the last QsnSetOutAdr operation 
is in effect. 


This command corresponds indirectly to the 5250 Write to Display command (WTD) with a Set Buffer 


Address order. (For an indirect operation, a WTD is placed in the command buffer only if one does not 
already exist in that buffer.) 


Authorities and Locks 


None 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. Either the field ID or the row and 
column parameters must be specified. 


Row 
INPUT; BINARY(4) 
The row at which to set the display address. This parameter is required if the field ID is not 
specified. 

Column 
INPUT; BINARY(4) 
The column at which to set the display address. This parameter is required if the field ID is not 
specified. 

Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the display address is set to the specified location. 


Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA301 E Command buffer is full. 


CPFA303 E Error occurred for screen I/O operation. 


CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


Write Data (QsnWrtDta) API 


Required Parameter Group: 


1 Data Char(*) 
2 Data length Binary(4) 


Omissible Parameter Group: 


Field ID Input Binary(4) 
Row Input Binary(4) 
Column Input Binary(4) 


Starting monochrome Input Char(1) 
attribute 


Ending monochrome attribute Input Char(1) 
Starting color attribute Input Char(1) 
Ending color attribute Input Char(1) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code V/O Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Data (QsnWrtDta) API writes data to the display at a given row and column using standard 
attributes. If a command buffer is specified that does not contain a previous or current WTD command, one 
is implicitly added to the buffer using the control characters QSN_CC1_NULL and 
QSN_CC2_UNLOCKBD. The display address after this operation will be one position past the last data 
byte written to the screen (including the ending screen attribute, if any). 


This command corresponds indirectly to the 5250 Write to Display command (WTD) with a Set Buffer 
Address order if the row and column are specified. (For an indirect operation, a WTD is placed in the 
command buffer only if one does not already exist in that buffer.) 


Restrictions 


If window mode is not set and the data (including attributes) exceeds the length of a row, the data will be 
wrapped to the next line. If bottom-to-top wrapping is not supported, a CPFA308 error occurs when the 
data (including attributes) exceeds the last row on the screen. If window mode is set, data that exceeds the 
width of the window will not be truncated or wrapped within the window, but will wrap across screen rows. 


>If the field ID given was created or last redefined by the QsnSetFldCC API, a CPFA346 will be signaled. 
This API should only be used to write data to fields that are not CCSID-capable. QsnWrtDta is only able to 
enforce this for fields that have an associated field ID, however. *& 


Authorities and Locks 


None 


Required Parameter Group 


Data 
INPUT; CHAR(*) 


The data to be written to the screen. If the data being passed is graphic DBCS, the data must be 
enclosed by extended ideographic attributes. (Use the Write Data (QsnWrtDta) API to specify the 
data stream Write Extended Attribute order. See the 5250 Functions Reference, SA21-9247, for 
further details.) 


Data length 
INPUT; BINARY(4) 


The number of characters contained in the data parameter. 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. If neither the field ID nor the row 
and column parameters are specified, the current display address is used. 


Row 
INPUT; BINARY(4) 


The row at which to write the data. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 


occurs if an incorrect row value is specified. 


If both the field ID and the row and column parameters are omitted, the data is written starting at 
the current display address. If this is the case and the command is a direct operation, or the buffer 
specified does not contain a preceding output operation that sets the display address, the current 
display address is set to row 1, column 1 prior to writing the data. 


Row and column must both be specified or omitted; one cannot be specified if the other is omitted. 
Column 
INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the center window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Starting monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no initial attribute is written to the display for the data. 


The monochrome and color attributes parameters are the initial and ending screen attributes: an 
initial and ending screen attribute to be used for a monochrome or a color display, respectively. 
One of these parameters will be selected based on the underlying display type, and the other will be 
discarded. Any of the attributes can be specified as a special value, X'00', indicating that no screen 
attribute should be written to the display. If the initial screen attribute is specified as an actual 
attribute, the data column, if specified, must be greater than or equal to 2. The initial screen 
attribute, if not X'00', will be written to the screen at the column previous to the first data character 
if row and column are specified, otherwise to the current display address. The ending screen 
attribute, if not X'00', will be written at the column directly after the last data character. See Screen 


Attribute Characters for a description of the screen attribute values. 


Ending monochrome attribute 
INPUT; CHAR(1) 


The ending screen attribute for monochrome displays. If this parameter is omitted, and 
monochrome attributes are to be used, no ending attribute is written to the display for the data. 


Starting color attribute 
INPUT; CHAR(1) 
The initial screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no initial attribute is written to the display for the data. 
Ending color attribute 
INPUT; CHAR(1) 


The ending screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no ending attribute is written to the display for the data. 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the data is written to the screen at the specified location. 
Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 

CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 

CPFA301 E Command buffer is full. 

CPFA303 E Error occurred for screen I/O operation. 

CPFA304 E Data-stream error &1 reported for screen I/O operation. 
CPFA305 E Cannot add operation to command buffer. 

CPFA307 E Screen position &1, &2 outside of display or window area. 
CPFA308 E Attempt to write data past end of display. 

CPFA30D E Invalid screen attribute. 

CPFA31D E Attempt to write outside of window area. 

CPFA31E E Required parameter &1 omitted. 

CPFA331 E Buffer handle incorrect. 

CPFA333 E Parameter &1 not positive integer value. 


CPFA334 E Low level environment handle incorrect. 


CPFA335 E 
CPFA33C E 
CPFA33F E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


a 
CPFA346 E 


% 


Screen address parameter error. 
Undefined field ID &1. 

Error occurred during data conversion. 
Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


Operation for field ID &1 not valid. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


»Write Data with CCSID (QsnWrtDtaCC) API 


Required Parameter Group: 


1 Data Char(*) 
2 Data length Binary(4) 


Omissible Parameter Group: 


Field ID Binary(4) 
CCSID Binary(4) 
Row Binary(4) 
Column Binary(4) 
Starting monochrome attribute Char(1) 
Ending monochrome attribute Char(1) 
Starting color attribute Char(1) 
Ending color attribute Char(1) 
Command buffer handle Binary(4) 
Low-level environment handle Binary(4) 
Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Data with CCSID (QsnWrtDtaCC) API writes data to the display at a given row and column 
using standard attributes. If a command buffer is specified that does not contain a previous or current WTD 
command, one is implicitly added to the buffer using the control characters QSN_CC1_NULL and 
QSN_CC2_UNLOCKBD. The display address after this operation will be one position past the last data 
character position written to the screen (including the ending screen attribute, if any). 


This command corresponds indirectly to the 5250 Write to Display command (WTD) with a Set Buffer 
Address order and Structured Field order if the row and column are specified. (For an indirect operation, a 
WTD is placed in the command buffer only if one does not already exist in that buffer.) 


Note: CDRA conversion is not performed upon this data. 


Restrictions 


If window mode is not set and the data (including attributes) exceeds the length of a row, the data will be 
wrapped to the next line. If bottom-to-top wrapping is not supported, a CPFA308 error occurs when the 
data (including attributes) exceeds the last row on the screen. If window mode is set, data that exceeds the 
width of the window will not be truncated or wrapped within the window, but will wrap across screen rows. 


If the field ID given was created or last redefined by the QsnSetFld API, a CPFA346 will be signaled. This 
API should only be used to write data to CCSID-capable fields. QsnWrtDtaCC is only able to enforce this 
for fields that have an associated field ID, however. 


QsnWrtDtaCC does not validate the data passed to it. If the data is invalid for some reason, an exception 
may occur if the control unit encounters improperly coded CCSID-based data. QsnWrtDta is not able to 
truncate data if it does not fit within the bounds of a field or low level environment window area as 
QsnWrtDta does for EBCDIC data. 


This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue 
this command to a control unit that does not support it. 


At this time, the CCSID given must have a unicode encoding scheme, otherwise a CPF3BDE will be 
signaled. 


Authorities and Locks 


None. 


Required Parameter Group 


Data 
INPUT; CHAR(*) 


The data in the CCSID given by the CCSID parameter to write to the screen. 
Data length 
INPUT; BINARY(4) 


The number of bytes contained in the data parameter. 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. If neither the field ID nor the row 
and column parameters are specified, the current display address is used. If this parameter is 
specified with a nonzero value, the CCSID parameter is also ignored, and the data written to the 
screen is assumed have the same CCSID as the field ID. 


CCSID 
INPUT; BINARY(4) 


The CCSID of the data to be written. If the CCSID given is not supported by the device, a 
CPF3BDE is signaled. 


If this parameter is omitted (zero is passed in as the CCSID), and the field ID parameter was 
omitted or previously undefined, the job CCSID is used. If the job CCSID is 65535, the default job 
CCSID is used instead. 


Row 
INPUT; BINARY(4) 


The row at which to write the data. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


If both the field ID and the row and column parameters are omitted, the data is written starting at 
the current display address. If this is the case and the command is a direct operation, or the buffer 
specified does not contain a preceding output operation that sets the display address, the current 
display address is set to row 1, column 1 prior to writing the data. 


Row and column must both be specified or omitted; one cannot be specified if the other is omitted. 
Column 
INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the right window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Starting monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no initial attribute is written to the display for the data. 


The monochrome and color attributes parameters are the initial and ending screen attributes: an 
initial and ending screen attribute to be used for a monochrome or a color display, respectively. 
One of these parameters will be selected based on the underlying display type, and the other will be 
discarded. Any of the attributes can be specified as a special value, X'00', indicating that no screen 
attribute should be written to the display. If the initial screen attribute is specified as an actual 
attribute, the data column, if specified, must be greater than or equal to 2. The initial screen 
attribute, if not X'00', will be written to the screen at the column previous to the first data character 
if row and column are specified, otherwise to the current display address. The ending screen 
attribute, if not X'00', will be written at the column directly after the last data character. See Screen 


Attribute Characters for a description of the screen attribute values. 


Ending monochrome attribute 


INPUT; CHAR(1) 
The ending screen attribute for monochrome displays. If this parameter is omitted, and 
monochrome attributes are to be used, no ending attribute is written to the display for the data. 
Starting color attribute 
INPUT; CHAR(1) 
The initial screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no initial attribute is written to the display for the data. 
Ending color attribute 
INPUT; CHAR(1) 
The ending screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no ending attribute is written to the display for the data. 
Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the data is written to the screen at the specified location. 


Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error code 


parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3BDE E CCSID &1 not supported by API. 


CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA308 E 
CPFA30D E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA33F E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA346 E 


% 


Introduced: V5R2 


Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Attempt to write data past end of display. 

Invalid screen attribute. 

Attempt to write outside of window area. 

Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Error occurred during data conversion. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 


Operation for field ID &1 not valid. 
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Write Structured Field Major (QsnWrtSFMaj) 
API 


Required Parameter Group: 


1 Major structure Char(*) 
2 Major structure length Binary(4) 


Omissible Parameter Group: 


Field ID Binary(4) 
Row Binary(4) 
Column Binary(4) 
Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Structured Field Major (QsnWrtSFMaj) API writes the major structure of a structured field, 
setting the display address to the given row and column. If a command buffer is specified that does not 
contain a previous or current WTD operation, one is implicitly added to the buffer using the control 
characters QSN_CC1_NULL and QSN_CC2_UNLOCKBD. 


Use this API in conjunction with the Write Structured Field Minor (QsnWrtSFMin) API to construct a 
structured field operation. For indirect operations, the length contained in the minor structure data 
parameter is added to the stored length for this major structure for every indirect QsnWrtSFMin operation 
encountered directly after this operation. In this way, you need only calculate the length of each individual 
structure for constructing a structured field operation. See the 5494 Remote Control Unit Functions 
Reference, SC30-3533, for more information regarding structured fields. 


This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer 
Address and a Write to Display Structured Field order if the row and column are specified. (For an indirect 
operation, a WTD is placed in the command buffer only if one does not already exist in the buffer.) 


Authorities and Locks 


None 


Restrictions 


If window mode is not set and the data (including attributes) exceeds the length of a row, the data will be 
wrapped to the next line. If bottom-to-top wrapping is not supported, a CPFA308 error occurs when the 
data (including attributes) exceeds the last row on the screen. 


Not all structured field types are supported by all devices. A negative response code is issued if an attempt 
is made to write a type to a device that does not support it. 


Required Parameter Group 


Major structure 
INPUT; CHAR(*) 


The major structure to be written to the screen. The data must consist of the entire major structure 
as documented in the 5494 Remote Control Unit Functions Reference, SC30-3533. 


Major structure length 
INPUT; BINARY(4) 


The length of the major structure parameter. This is the length only and does not include any 
associated minor structure lengths. 


Omissible Parameter Group 


Field ID 
INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. If neither the field ID nor the row 
and column parameters are specified, the current display address is used. 


Row 
INPUT; BINARY(4) 


The row at which to write the structure. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


If both the field ID and the row and column parameters are omitted, the data is written starting at 


the current display address. If this is the case and the command is a direct operation, or the buffer 

specified does not contain a preceding output operation that sets the display address, the current 

display address is set to row 1, column 1 prior to writing the data. 

Row and column must both be specified or omitted; one cannot be specified if the other is omitted. 
Column 

INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the center window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Command buffer handle 
INPUT; BINARY(4) 
A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the data is written to the screen at the specified location. 


Otherwise, this is an indirect operation and the command is stored in the command buffer without 
an I/O operation taking place. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 


CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA308 E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA341 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Screen position &1, &2 outside of display or window area. 
Attempt to write data past end of display. 

Attempt to write outside of window area. 

Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Length &2 of structure incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Write Structured Field Minor (QsnWrtSFMin) 
API 


Required Parameter Group: 


Minor structure Char(*) 
Minor structure length Binary(4) 
Command buffer handle Binary(4) 


Omissible Parameter Group: 


4 Low-level environment handle Binary(4) 
5 Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Write Structured Field Minor (QsnWrtSFMin) API writes the minor structure of a structured field, 
incrementing the length field in the corresponding major structure by the length of this minor structure. The 
QsnWrtSFMin API must directly follow a QsnWrtSFMaj or QsnWrtSFMin operation to the given 
command buffer. 


Use this API in conjunction with the Write Structured Field Major (QsnWrtSFMaj) API to construct a 
structured field operation. For indirect operations, the length contained in the minor structure data 
parameter is added to the stored length for this major structure for every indirect QsnWrtSFMin operation 
encountered directly after this operation. In this way, you need only calculate the length of each individual 
structure for constructing a structured field operation. See the 5494 Remote Control Unit Functions 
Reference, SC30-3533, for more information regarding structured fields. 


Authorities and Locks 


None. 


Restrictions 


Not all structured field types are supported by all devices. A negative response code is issued if an attempt 
is made to write a type to a device that does not support it. 


Required Parameter Group 


Minor structure 
INPUT; CHAR(*) 
The minor structure to be written to the screen. The data must consist of the entire minor structure 
as documented in the 5494 Remote Control Unit Functions Reference, SC30-3533. 
Minor structure length 
INPUT; BINARY(4) 


The length of the minor structure. 
Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. The last operation stored in this 
command buffer must have been either a QsnWrtSFMaj or QsnWrtSFMin operation. 


Omissible Parameter Group 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error code 


parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA307 E 
CPFA308 E 
CPFA30D E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33B E 
CPFA33C E 
CPFA341 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 
Screen position &1, &2 outside of display or window area. 
Attempt to write data past end of display. 
Invalid screen attribute. 

Attempt to write outside of window area. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 
Low level environment handle incorrect. 
Screen address parameter error. 

Incorrect operation before QsnWrtSFMin. 
Undefined field ID &1. 

Length &2 of structure incorrect. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Write to Display (QsnWTD) API 


Required Parameter Group: 


1. Control character byte 1 
2 Control character byte 2 


Omissible Parameter Group: 


Command buffer handle Binary(4) 


Low-level environment Binary(4) 
handle 


Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Write to Display (QsnWTD) API issues a Write to Display (WTD) command. A WTD command is 
used to indicate the beginning of a series of output operations. For most of the DSM screen output 
operations, the control unit requires that a WTD be issued prior to the actual operation itself, in the same 
I/O operation. Multiple output operations can be sent with a given WTD command by using a command 
buffer. For direct operations, such output APIs, implicitly issue a WTD command. For indirect operations, a 
WTD is added to the buffer if one does not exist already. Each time a WTD command is received, the 
control unit implicitly sets the display address to row 1, column 1, prior to issuing the operation. 


For example, if two direct QsnWrtDta operations are performed in succession and the second operation 
does not specify the row and column parameters, the data is written to row 1, column 1, and not the display 
address following the first QsnWrtDta operation. If two indirect QsnWrtDta operations are issued to an 
empty command buffer, the first QsnWrtDta operation causes a WTD command to be added to the buffer, 
but the second QsnWrtDta operation can use the existing command. In this case, if no row and column are 
specified, the display address used for the second operation will be the one after the first operation is issued. 
If an intervening operation that does not require a WTD, such as a QsnClrScr or a QsnSetErr, is added to 
the command buffer between two operations that do require a WTD command, a second WTD command is 
added to the buffer for the second operation. 


The screen output APIs that require a WTD command and that correspond to the WTD command orders 
(as described in 5250 Functions Reference, SA21-9247) are as follows: 


Set Output Address (QsnSetOutAdr) 


Write Data (QsnWrtDta) 


Write Transparent Data (QsnWrtTDta) 

Pad for N Positions (QsnWrtPad) 

Pad between Two Screen Addresses (QsnWrtPadAdr) 

Set Field (QsnSetFld) 

Set Cursor Address (QsnSetCsrAdr) 

Insert Cursor (QsnInsCsr) 
The cursor position is not affected if the keyboard is unlocked when command processing begins and is not 
locked during command processing, or if a parameter error is detected. If specified by control character 


byte 1, the cursor will be moved to the insert cursor or default location when the keyboard is unlocked. 


This operation corresponds directly to the 5250 Write to Display command. If this is an indirect operation, 
this operation will issue anew WTD command to the command buffer. 


Authorities and Locks 


None 


Required Parameter Group 


Control character byte 1 
INPUT; CHAR(1) 


The operation for the display to perform prior to processing the Write to Display command. See 
Control Characters for a description of the control character values. 


Control character byte 2 
INPUT; CHAR(1) 


The operation for the display to perform after the Write to Display command has been processed. 
See Control Characters for a description of the control character values. 


Omissible Parameter Group 


Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is omitted or 
specified as 0, this is a direct operation and the command is sent to the display. Otherwise, this is an 
indirect operation and the command is stored in the command buffer without an I/O operation 
taking place. 


Low-level environment handle 
INPUT; BINARY(4) 


The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA303 E 
CPFA304 E 
CPFA305 E 
CPFA31C E 
CPFA31E E 
CPFA331 E 
CPFA334 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Error occurred for screen I/O operation. 
Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 
Incorrect value for control character byte &1. 
Required parameter &1 omitted. 

Buffer handle incorrect. 

Low level environment handle incorrect. 
Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 
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Write Transparent Data (QsnWrtTDta) API 


Required Parameter Group: 


1 Data Char(*) 
2 Data length Binary(4) 


Omissible Parameter Group: 


Field ID Input Binary(4) 
Row Input Binary(4) 
Column Input Binary(4) 


Starting monochrome Input Char(1) 
attribute 


Ending monochrome attribute Input Char(1) 
Starting color attribute Input Char(1) 
Ending color attribute Input Char(1) 
Command buffer handle Input Binary(4) 


Low-level environment Input Binary(4) 
handle 


Error code V/O Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Transparent Data (QsnWrtTDta) API writes n bytes of transparent data to the display. 


This command allows transmission of data with any value (X'00' to X'FF’) to the display screen. If the data 
destination is a 5250 display, and if the data X'04', X'11', or X'FF' is transmitted, unpredictable results 
occur. Note that if DBCS characters are included in the data, the host system does not perform IGC 
extension character processing. However, SI/SO characters will be processed correctly. 


The display address after this operation is one position past the last data byte written to the screen. 
This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer 


Address and a Transparent Data order. (For an indirect operation, a WTD is placed in the command buffer 
only if one does not already exist in that buffer.) 


Authorities and Locks 


None 


Restrictions 


This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue 
this command to a control unit that does not support it. Additional restrictions apply as for the Write Data 
(QsnWrtDta) API. 


“>If the field ID given was created or last redefined by the QsnSetFldCC API, a CPFA346 will be signaled. 
This API should only be used to write data to fields that are not CCSID-capable. QsnWrtTDta is only able 
to enforce this for fields that have an associated field ID, however.*& 


Required Parameter Group 


Data 

INPUT; CHAR(*) 

The data to be written to the screen. 
Data length 


INPUT; BINARY(4) 


The number of bytes of data to be written. 


Omissible Parameter Group 


Field ID 


Row 


INPUT; BINARY(4) 


The field ID indicating the field at which to set the display address. If this parameter is specified 
with a nonzero value, the row and column parameters are ignored and the row and column values 
corresponding to the field ID are used to set the display address. If neither the field ID nor the row 
and column parameters are specified, the current display address is used. 


INPUT; BINARY(4) 


The row at which to write the data. The row parameter must refer to a row no greater than the 
current screen or window mode height (if window mode is enabled). The actual screen row used for 
a screen I/O operation is calculated using the formula base+offset=actual. The base is the row 
location of the top window border (0 for full screen) if offset is positive, or the row location of the 
bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the 
row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error 
occurs if an incorrect row value is specified. 


If both the field ID and the row and column parameters are omitted, the data is written starting at 
the current display address. If this is the case and the command is a direct operation, or the buffer 


specified does not contain a preceding output operation that sets the display address, the current 
display address is set to row 1, column 1, prior to writing the data. Row and column must both be 
specified or omitted; one cannot be specified if the other is omitted. 


Column 
INPUT; BINARY(4) 


The column at which to write the data. The column parameter must refer to a column no greater 
than the current screen or window mode width (if window mode is on). The actual screen column 
used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the 
column location of the left window border (0 for full screen) if offset is positive, or the column 
location of the center window border (screen width plus 1 for full screen) if offset is negative. The 
offset is the column parameter value specified, and actual is the actual screen column to be used. A 
CPFA307 error occurs if an incorrect column value is specified. 


Starting monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no initial attribute is written to the display for the data. See Screen 


Attribute Characters for a description of the screen attribute values. The attribute parameters are 
specified with the same effect as for the QsnWrtDta operation. 


Ending monochrome attribute 
INPUT; CHAR(1) 
The ending screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no ending attribute is written to the display for the data. 
Starting color attribute 
INPUT; CHAR(1) 
The initial screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no initial attribute is written to the display for the data. 
Ending color attribute 
INPUT; CHAR(1) 
The ending screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no ending attribute is written to the display for the data. 
Command buffer handle 
INPUT; BINARY(4) 


A handle for the command buffer in which to store the command. If this parameter is specified, this 
is an indirect operation; the command is stored in the command buffer without an I/O operation 
taking place. If this parameter is omitted or specified with a zero value, this is a direct operation; 
the data is written to the screen at the specified location. 


Low-level environment handle 
INPUT; BINARY(4) 
The low-level environment that the operation applies to. If this parameter is omitted or given with a 
value of zero, the default low-level environment is used. 
Error code 
VO; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA301 E 
CPFA304 E 
CPFA305 E 
CPFA306 E 
CPFA307 E 
CPFA31E E 
CPFA31D E 
CPFA31E E 
CPFA331 E 
CPFA333 E 
CPFA334 E 
CPFA335 E 
CPFA33C E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


ao 
CPFA346 E 


“4 


Error Message Text 

Severe error while addressing parameter list. 

Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Command buffer is full. 

Data-stream error &1 reported for screen I/O operation. 
Cannot add operation to command buffer. 

Command not supported by current device. 

Screen position &1, &2 outside of display or window area. 
Required parameter &1 omitted. 

Attempt to write outside of window area. 

Required parameter &1 omitted. 

Buffer handle incorrect. 

Parameter &1 not positive integer value. 

Low level environment handle incorrect. 

Screen address parameter error. 

Undefined field ID &1. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


Operation for field ID &1 not valid. 
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Low-Level Services Examples 


Low-Level Services Example--1 


The sample ILE C program in Figure 1 shows how to use the Write Data (QsnWrtDta), Get AID (QsnGetAID), and Roll 
Up (QsnRollUp) APIs. The program writes a line at the bottom of the screen and if F3 is not pressed, rolls the screen up 
and writes a new line at the bottom of the screen. The roll area for the QsnRollUp API is defined to be from row | to 24 
and one line is rolled up. If F3 is pressed, the program ends. A partial screen display is shown in Figure 2. 


Figure 1. Program to Roll Text on Screen 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "qsnapi.h" 


int main(void) 
{ 
long i; 
char s[100]; 


QsnClrScr('0O', O, O, NULL); 
for (i = 1; ; ++i) { 

sprintf(s, "Line %2.d. 

OsnWrtDta(s, strlen(s), 

QSN_SA_NORM, 

if (QsnGetAID (NULL, 0, 

break; 
QsnRollUp(1, 1, 24, 0, 


Press Enter to roll, F3 to quit.", 
0, 24, 2, QSN_SA_NORM, QSN_SA_NORM, 
QSN_SA_NORM, 0, 0, NULL); 
NULL) == QSN_F3) 


0, NULL); 


Figure 2. Screen Output from Roll Text Program 


i); 


Low-Level Services Example--2 


Figure 3 shows how to use the Query 5250 (QsnQry5250) API. A sample display is shown in Figure 4. 


Figure 3. Program Using the Query 5250 (QsnQry5250) API 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "qsnapi.h" 


#define TRUE 
#define FALSE 0 


int main(void) 
{ 
Qsn_Qry_5250_T qry5250; 
Qsn_WSC_display_T *dsp = (Qsn_WSC_display_T *) (qry5250.WSC_display) ; 
char s[100]; 
Q Bin4 row; 
Qsn_Cmd_Buf_T buf; 


QOsnOry5250 (€qry5250, sizeof (qry5250), NULL); 

buf = QsnCrtCmdBuf (100, 20, 0, NULL, NULL); 

QsnClrScr('0O', buf, Q_NO_HANDLE, NULL); 

sprintf(s, "Query status is %c, num input fields: %d, color: %c, wide: 


qry5250.query_status, qry5250.num_input_capable, 
(OQsnQryColorSup (NULL, Q_NO_HANDLE, NULL) == TRUE ? 'Y' : 'N'), 
(dsp->scr_size == 3 ? 'Y' : 'N')); 

QOsnWrtDta(s, strlen(s), 0, row=5, 5, QSN_SA_ NORM, QSN_SA_ NORM, 


QSN_SA_NORM, QSN_SA_ NORM, buf, ) NO_HANDL 
sprintf(s, "GUI display: %d, GUI support: %d", 
dsp->GUI_display, dsp->GUI_support); 
QOsnWrtDta(s, strlen(s), 0, rowt=2, 5, QSN_SA_ NORM, QSN_SA_NORM, 


Gl 


, NULL) ; 


QSN_SA_ NORM, QSN_SA_ NORM, buf, Q_ NO_HANDLE, NULL); 
sprintf(s, "Move cursor: %d, Rowl/Coll: %d, ReadMDTImmAlt: %d", 

dsp->move_csr_order, dsp->rowl_coll, dsp->Read_MDT_Imm_Alt) ; 
QOsnWrtDta(s, strlen(s), 0, row +=2, 5, QSN_SA NORM, QSN_SA_ NORM, 
QSN_SA_ NORM, QSN_SA_ NORM, buf, Q_NO_HANDLE, NULL) ; 
sprintf(s, "Extended primary attributes: %d, DBCS: %x", 

dsp->extended_pri_atr_DP, dsp->DBCS) ; 
QOsnWrtDta(s, strlen(s), 0, row +=2, 5, QSN_SA NORM, QSN_SA_ NORM, 
QSN_SA_NORM, QSN_SA_ NORM, buf, Q_NO_HANDLE, NULL) ; 
sprintf(s, "Wide mode on: %c", 

QsnRtvMod (NULL, Q_NO_HANDLE, NULL) == QSN_DSP04 ? 'y' : 'n'); 
QOsnWrtDta(s, strlen(s), 0, row +=2, 5, QSN_SA_ NORM, QSN_SA NORM, 

QSN_SA_ NORM, QSN_SA_NORM, buf, Q_ NO_HANDLE, NULL); 

sprintf(s, "Wide mode allowed: %c", 

QsnQryModSup (QSN_DSP04, NULL, Q_NO_HANDL 


QsnWrtDta(s, strlen(s), 0, 13, 5, QSN_SA_ NORM, QSN_SA_ NORM, 
QSN_SA_NORM, QSN_SA_NORM, buf, Q_NO_HANDLE, NULL); 
QOsnPutBuf (buf, Q_NO_HANDLE, NULL); 

QOsnGetAID (NULL, Q_NO_HANDLE, NULL) ; 


Figure 4. Screen Output from QsnQry5250 API Program 


Query status is 1, num input fields: 500, color: Y, wide: Y 


GUI display: 1, GUI support: 1 


Move cursor: 0, Extended primary attributes: 0 


Wide mode on: n 


Wide mode allowed: y 


Low-Level Services Example--3 


The sample program in Figure 5 shows how to use the Read Modified Fields (QsnReadMDT) API in conjunction with the 
buffer query APIs. The resulting screen display before and after the input operations is shown in Figure 6 and Figure 7, 


respectively. 


Figure 5. Program Using Read Modified Fields (QsnReadMDT) API 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "qsnapi.h" 


#define TRUE 
#define FALS 


Gl 
lo) 


int main(void) 
{ 
Q Bin4 i, tl, t2, t3, numflds; 
const Q_Uchar ccl=QSN_CC1_MDTALL_CLRALL, cc2=QSN_CC2_UNLOCKBD; 
const Q _Uchar nosa = QSN_NO_SA, norm = QSN_SA_NORM, saul = QSN_SA_UL; 
char pad = ' '; 
Qsn_Cmd_Buf_T cmdbuf, cmdbuf2; 
Qsn_Inp_Buf_T inpbuf; 
Qsn_Fld_Inf_T fldqry; 
Qsn_Read_Inf_T rdqry; 
char msg[100]; 
Q Fdbk_T fdbk = { sizeof(Q_Fdbk_T) }; 


emdbuf = QsnCrtCmdBuf (100, 50, O, NULL, NULL); 
emdbuf2 = QsnCrtCmdBuf(100, 50, 0O, NULL, NULL); 
inpbuf = QsnCrtInpBuf (200, 50, 0, NULL, NULL) 
QsnClrScr('0O', 0, O, NULL); 
QsnWTD(ccl, cc2, cmdbuf, 0, NULL); 
while (TRUE) { 
QsnSetFld(0, 10, 3, 2, QSN_FFW_ALPHA_SHIFT, NULL, 0, saul, 
saul, cmdbuf, 0, NULL); 
QsnSetFld(0, 10, 5, 2, QSN_FFW_ALPHA_SHIFT, NULL, 0, saul, 
saul, cmdbuf, 0, NULL); 
QsnSetFld(0, 10, 7, 2, QSN_FFW_ALPHA_SHIFT, NULL, 0, saul, 
saul, cmdbuf, 0, NULL); 


, 


numflds = QsnReadMDT (QSN_CC1_NULL, QSN_CC1_NULL, NULL, 
inpbuf, cmdbuf, 0, NULL); 
if (QsnRtvReadAID(inpbuf, NULL, NULL) == QSN_F3) 
break; 
QsnPutBuf (cmdbuf2, 0, NULL); 
QOsnClrBuf (cmdbuf2, NULL); 
QsnClrBuf (cmdbuf, NULL); 
QsnWTD(ccl, cc2, cmdbuf, 0, NULL); 
sprintf(msg, "Num Fields Change: %d", numflds) ; 
QsnWrtDta(msg, strlen(msg), 0, 2, 30, norm, norm, norm, norm, 
cmdbuf, 0, NULL); 
for (i = 1; i <= numflds; itt) { 
fldgry.len = 0; 
if (QsnRtvFldiInf(inpbuf, i, &fldqry, sizeof(fldqry), 
0, &fdbk) != QSN_FAIL) { 


sprintf (msg, 

"Field# %d, row %d, col %d, len %d, value %.*s", 
i, fldgqry.row, fldqry.col, fldqry.len, 
fldgry.len, fldqry.data); 

QsnWrtDta(msg, tl=strlen(msg), 0, 

t2=i+3, t3=30, norm, norm, norm, norm, 

cmdbuf, 0, NULL); 

QsnWrtPad(pad, tl, 0, t2, t3, cmdbuf2, 0, NULL); 

} else { 
sprintf(msg, "Field query failed"); 
QsnWrtDta(msg, tl=strlen(msg), 0, 

t2=4, t3=30, norm, norm, norm, norm, 

cmdbuf, 0, NULL); 

QsnWrtPad(pad, tl, 0, t2, t3, cmdbuf2, 0, NULL); 


} 


QsnRtvReadInf (inpbuf, &rdqry, sizeof(rdqry), 0, NULL); 
sprintf(msg, "Read information:"); 


QsnWrtDta(msg, strlen(msg), 0, t2=10, t3=2, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

QsnWrtPadAdr (pad, -1, -1, t2, t3, cmdbuf2, 0, NULL); 

sprintf(msg, "Bytes returned %d, available: %d", 
rdqry.bytes_returned, rdqry.bytes_available) ; 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+2, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

sprintf(msg, "First data byte: %p", rdgqry.dta); 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+2, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

sprintf(msg, "First field byte: %p", rdqry.fld_dta); 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+4, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

sprintf(msg, "Diff: %d", rdgqry.fld_dta-rdqry.dta)j; 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+4, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

sprintf (msg, 


"Read len: %d, data len: %d, field data len: %d,\ 

num fields: $d", 
rdqry.read_len, rdqry.dta_len, rdgqry.fld_dta_len, 
rdgry.num_flds); 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+2, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 

sprintf(msg, "Read row: %d, col: %d, aid: %x", 
rdqry.read_row, rdqry.read_col, rdqry.AID); 

QsnWrtDta(msg, strlen(msg), O, ++t2, t3+2, norm, norm, 
norm, norm, cmdbuf, 0, NULL); 


Figure 6. Display Screen before Input Operation 


Figure 7. Display Screen after Input Operation 


Num Fields 


Field# 1, col 2, len 7, value field 1 


Field# 2, col 2, len 9, value field 2 


Field# 3, col 2, len 7, value field 3 


Read information: 


Bytes returned 80, available: 80 


First data byte: SPP:0000 :laefQPADEVOO1LOJENNIFER 002600 :19b:0:d42 


First field byte: SPP:0000 :laefQPADEVOO1LOJENNIFER 002600 :19e:1:d42 


Darr: 3 


Read len: 35, data len: 35, field data len: 32, num fields: 3 


Read row: 3, col: 2, aid: f1 


Low-Level Services Example--4 


The sample program in Figure 8 shows how to use the QsnWrtSFMaj and QsnWrtSFMin APIs to display a window on the 
screen using the 5250 Create Window command. See the 5494 Remote Control Unit Functions Reference R3.1, 
SC30-3533-04, for more information. This book can be viewed online through the IBM Publications Center. 


Figure 8. Program Using Read QsnWrtSFMaj and QsnWrtSFMin APIs 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "qsnapi.h" 


#define STRUCTURED_FIELD "\xd9! 
#define CREATE _WIN_STRUCTURED_FIELD "\x51! 
#define WINDOW_CURSOR_RESTRICT "\x80' 
#define WINDOW_PULL_DOWN "\x40' 


#define WINDOW_BORD 
#define WINDOW_TITL 


R_MINOR "\x01' 
_ MINOR "\x10! 


typedef _Packed struct { 


Q Bin2 length; 
Q Uchar class; 
Q Uchar type; 
Q Uchar flagl; 
Q Uchar flag2; 
Q Uchar reserved; 
Q Uchar num_rows; 
Q Uchar num_cols; 


} create_window_major; 


typedef _Packed struct { 


Q Uchar length; 

Q Uchar type; 

Q Uchar flagl; 

Q Uchar mono_attr; 
Q Uchar color_attr; 
Q Uchar ul; 

Q Uchar top; 

Q Uchar ur; 

Q Uchar left; 

Q Uchar right; 

Q Uchar 11; 

Q Uchar bottom; 

Q Uchar lr; 


} create_window_border_minor; 


typedef _Packed struct { 


Q Uchar length; 

Q Uchar type; 

Q Uchar flagl; 

Q Uchar mono_attr; 
Q Uchar color_attr; 
Q Uchar reserved; 


} create_window_title_minor; 


int main(void) 


{ 


create_window_major win; 
create_window_border_minor win_border; 
create_window_title_minor win_title; 
Qsn_Cmd_Buf_T cmdbuf; 

Q Uchar cl; 

char title_text[] = "Title"; 


cmdbuf = QsnCrtCmdBuf( 300, 20, 0, NULL, NULL); 


/* setup Create window command major structure */ 


win.length = sizeof (win); 


win.class = STRUCTURED_FIELD; 
win.type = CREATE_WIN_STRUCTURED_FIELD; 
win.flagl = WINDOW_CURSOR_RESTRICT; 


win.flag2 = '\x00'; 
win.reserved = '\x00'; 
win.num_rows = 10; 
win.num_cols = 10; 


/* write Create window command major structure to command buffer */ 
QOsnWrtSFMaj((char *) (&win), sizeof(win), 0, 9, 22, cmdbuf, 0, NULL); 


/* setup border presentation minor structure */ 
win_border.length = sizeof (win_border) ; 
win_border.type = WINDOW_BORDER_MINOR; 
win_border.flagl = '\x00'; 
win_border.mono_attr = QSN_SA RI; 
win_border.color_attr = QSN_SA_PNK; 


win_border.ul = '+'; 
win_border.top = '*'; 
win_border.ur = '+'; 
win_border.left = '-'; 
win_border.right = '|'; 
win_border.1l = '+'; 
win_border.bottom = '*'; 
win_border.1lr = '+'; 


/* write border presentation minor structure to command buffer */ 
QOsnWrtSFMin((char *) (&win_border), sizeof(win_border), cmdbuf, 0, NULL); 


/* setup window title minor structure */ 

win_title.length = sizeof (win_title) + strlen(title_text) ; 
win_title.type = WINDOW_TITLE_MINOR; 

win_title.flagl = '\x00'; 

win_title.mono_attr = QSN_SA_ BL; 

win_title.color_attr = QSN_SA_RED; 

win_title.reserved = '\x00'; 


/* write window title minor structure to command buffer */ 
QsnWrtSFMin((char *) (&win_title), sizeof (win_title), cmdbuf, 0, NULL); 


/* write title text to command buffer */ 
OsnWrtDta(title_text, strlen(title_text), 0, 0, O, 
QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, cmdbuf, 0, NULL); 


/* write command buffer to screen and wait for key-press */ 
QsnPutBuf (cmdbuf, 0, NULL); 
QOsnGetAID(NULL, 0, NULL); 
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5250 Data Stream Details 


AlD-Generating Keys 


The AID (attention indicator) code identifies to the host system the function being requested from the 
keyboard. The AID code is returned by certain input operations when the operator presses an 
AID-generating key. The following table lists the AID-generating keys and the AID codes associated with 
each key. See Format of the Low-Level Environment Description for instructions on how to specify an 


alternative help key. 


[AIDCodes 
[AIDkey = ‘|Mnemonic = = =————_: [AID Code 
Cmd 1 - 12 (cmd 1=x'31', cmd12=x'3C) |QSN_FI-QSN_FI200 SS sO'31'- x3 C 
[Selector Light Pen AutoEnter == [QSN_SLP  — s—<“‘(‘“‘“‘«‘<~iR BSC 
[Forward Edge Trigger AutoEnter == [QSN_FET— —~—™—=sO X'S 
PAL —(i‘“‘“‘iéS IQSNEPAT RC 
PAZ —“<i‘;}OWS!”~~C~C~C «XQ SN PAD oe 
[PAS —~—<“—t;s*s~sCCC:CSSS SQ SN PAB xoB 
[Cmd 13 - 24 (cmd 13=x'BI', cmd24=x'BC) QSN_FI3-QSN_F24 —Ss=C(X'I'- xB" 
[Clear i ists—“—=<is;~s™s™S™CCC::””C*é‘é*dQSNCLEAR—“(ststi‘“‘“‘“‘“‘<~ziRK BOSC 
[EnterorRecord Advance =———<Cs*si‘X@(QSNLENER~~~C~™XFS 
[Help (notinerror state) ==————iC«QSN-HELP—i—‘“—~sSCSK 
[Roll DownorPage Up ———~C~<C*«‘C:*«<C QSN_LROLLDOWNoor QSN_PAGEUP |x'F4 
[Roll UporPageDown =———~—S—CSQSSN_ROLLUP or QSN_PAGEDOWN||x'F5'5 
[Print ss —<—~s—‘“—;s*~*~*™:::””CSdQSNEPRINTO—™C*dSKG 
[Record Backspace ———(iti‘é;S)©)©)© (QSNRECBS Ci 


Control Characters 


The display control characters (CCs) are always specified as a pair of 1-byte fields. They are used on the 
QsnWTD, QsnReadInp, QsnReadMDT, and QsnReadMDTAIt APIs. These characters select specific 
operations for the display station to perform. Byte 1 is always processed first. When the CCs are used with 
the QsnWTD API, the first CC is processed immediately while the second CC is not processed until all the 
other information associated with the API has been processed. When used with an input operation, both 
CCs are processed after the operation has completed. The following two tables list the valid control 
character values and their associated mnemonics. 


[Control Character Byte 1 


MDT Flags 
in 


Nonbypass 
Mnemonic 0-2 |Keyboard |Fields 


N_CCL_NULL oo... 
IOSNCCLLOCKBDoor|x |||... |. 
[QSN_CCLMDTNBY ‘fom [x | x |||. 
QSN_CCI_MDTALL ou] x | T= if | 
[ QSN_CCL_CIRMOD[ioo[x | |. |..x |. 
[QSN_CCI_MDTNBY_CLRALL [ior |x |x ||. |x 
QSN_CCI_MDINBY_CLRMOD|I10 |x |x}. |x| 
[OSN_CCIL_MDTALL_CLRALL [1|.x | |x |. |. 


Note: 


~ 


~ 


~ 


~ 


~ 


~ 


~ 


1. Bits 3 through 7 are reserved and must be 0. A CPFA31C error will be issued if this is not the 
case. 


2. If there are no bypass fields with MDT flags on, then the master MDT will be cleared. 


Control Character Byte 2 


[Mnemonic | Bit [Meaning 
| | 0 [reserved 


QSN_CC2_NO_IC 1 0: Cursor moves to default or IC order 
position when keyboard unlocks 
1: Cursor does not move when keyboard 
unlocks 


QSN_CC2_RST_CSR_BL 2 0: no action 
1: Reset blinking cursor 


QSN_CC2_SET_CSR_BL 0: no action 
1: Set blinking cursor 


QSN_CC2_UNLOCKBD 0: no action 


1: Unlock the keyboard and reset any 
pending AID bytes 


QSN_CC2_ALARM 5 0: no action 

1: Sound alarm 
QSN_CC2_MSG_OFF 6 0: no action 

1: Set Message Waiting indicator off 
QSN_CC2_MSG_ON 7 0: no action 

1: Set Message Waiting indicator on 


Notes: 


e The mnemonics for control character byte 2 can be combined with a bitwise OR operation. 


e See notes in the 5250 data stream documentation for further details regarding these functions. 


Screen Attribute Characters 


The screen or field attributes control the image produced on the display station screen. Each attribute 
occupies one character position in the display station regeneration buffer and is displayed as a blank. The 
effect produced by an attribute begins at its location in the regeneration buffer and continues until the next 
attribute appears. The attributes for non-color displays are shown in the table below and for color displays 
in the Screen Attributes for Color Displays table. There are certain operations that allow a value to be 
specified for a screen attribute that indicates no screen attribute should be used. Where supported, the value 
is X'00' and the mnemonic is QSN_NO_SA. 


Screen Attributes for Non-Color Displays 


[Mnemonic | Bits [Value 
[QSN_SA_N ORM | 0-2 [oo1: Attribute identification flag 


QSN_SA_CS 3 0: Column separator off 

1: Column separator on 
QSN_SA_BL 4 0: Do not blink field 

1: Blink field 
QSN_SA_UL 5 0: Do not underscore field 

1: Underscore field 
QSN_SA_HI 6 0: Low intensity 

1: High intensity 
QSN_SA_RI 0: Normal image 

1: Reverse image 


| SA_ND | Ber display: equivalent to specifying QSN_SA_UL, 


ms SA_HI, and QSN_SA_RI. 
Note: a functions can be selected by combining the mnemonics with a bitwise OR operation. 


Screen Attributes for Color Displays 


[Mnemonic | Value [Meaning 


QSN_SA_GRN | x'20' Green 


(Green 
[QSN_SA_LGRN_RIs[sx'21"— ss |Green/ReverseImage —s— 
QSN_SA_WHT po x22) White 
[QSN_SALWHT_RI-s [| sx'23'. ss [White/ReverseImage ss 
[QSN_SALGRN_-UL sis sx'24’, ss |GreenfUnderscore 
[QSN_SA_GRN_UL RI [ss x'25'_— [Grreen/Underscore/ReverseImage 
REEL DE 
[Qs N_SA_ND | x'27' [Nondisplay 

QSN_ SA_RED po x28 Red 
[QSN_SA_RED_RIsisdfs'29"— ss Red/ReverseImage —s—‘“—~s—~S™S 
(QSN_SA_LRED_BL [| '2A"—s Red/Blink 


QSN_SA_RED_RI_BL [—-x'2B'—s [Red/Reverse Image/Blink = 
QSN_SA_RED_UL [= x2C’ Ss [Red/Underscore sss— 
QSN_SA_RED_UL_RI | x'2D'_—s [Red/Underscore/Reverse Image 
QSN_SA_RED_UL_BL | -x'2E"—s [Red/Underscore/Blink 
QSN_SA_ND_2F | x'2F-—sNondisplay 
QSN_SA_TRQ_CS | x30" [Turquoise/Column Separators 
QSN_SA_TRQ_CS_RI [ x31" [Turquoise/Column Separators/Reverse Image 
QSN_SA_YLW_CS [ x32". [Yellow/Column Separators 
QSN_SA_YLW_CS_RI | —-x’33' ——‘[Yellow/Column Separators/Reverse Image 
QSN_SA_TRQ_UL | ——sx'34" [Turquoise/Underscore 
QSN_SA_TRQ_UL_RI | —-x’35' ~——‘[Turquoise/Underscore/Reverse Image 
QSN_SA_YLW_UL | x36" [Yellow/Underscore ss 
QSN_SA_ND_37 [x37 [Nondisplay ssss—‘—s™sSCSCS 
QSN_SA_PNK [ x38" Pink 

QSN_SA_PNK_RI [ x39" Pink/ReverseImagess—s—S—s 
QSN_SA_BLU [0 BAT Bue 
QSN_SA_BLU_RI [ —-x3B'—s [Blue/ReverseImage = ——— 
QSN_SA_PNK_UL [| = -x3C's*Pink/Underscore sss 
QSN_SA_PNK_UL_RI | —~x’3D'_—s*[Pink/Underscore/ReverseImage 
QSN_SA_BLU_UL | —x’3E"——s[Blue/Underscore 
QSN_SA_ND_3F [| x3F) ss [Nondisplay 9 


Display Address 


The display address is the address at which data is displayed or a field definition begins. This can be 
modified explicitly with a Set Output Address (QsnSetOutAdr) call, or implicitly with output operations, 
such as those associated with the Write Data (QsnWrtDta) API, that accept a cursor position. The 5250 
Write to Display (WTD) command initializes the display address to row 1, column 1. Because each output 
operation contains a WTD command, this means that the display address is reset on each direct screen 
output operation. 


Insert Cursor Address 


The insert cursor (IC) order specifies the position of the cursor when the host system unlocks the keyboard 
and when the display station operator presses the Home key. The display address is not affected by this 
address. This can be set with the Insert Cursor (QsnInsCsr) API, and in some cases with the Set Cursor 
Address (QsnSetCsrAdr) API (only when the Move Cursor (MC) order is not supported). 


Modified Data Tag (MDT) Bit 


There is a modified data tag (MDT) bit for each input field and a master MDT bit. These bits are used to 
determine which fields should be returned in response to the Read Modified Fields (QsnReadMDT), Read 
Modified Alternate (QsnReadMDTAIt), and Read Modified Immediate Alternate (QsnReadMDTImmAIt) 
APIs. The MDT bit for a field and the master MDT bit can be set using bit 4 of the field format word (see 
Format of the Field Format Word) on a Set Field (QsnSetFld) API. The master MDT bit and the MDT bit 
for a field are set on anytime the operator types into or alters a field on the display. Once the bits are set, 
only a control character for resetting them (see Table 2), or a clear screen operation using the Clear Screen 


(QsnClrScr) API or a Start of Header order, can reset them. 


Resequencing 


Resequencing allows the control unit to return up to 128 input fields in any specified order. Resequencing is 
accomplished by chaining input fields together with Field Control Words specifying resequencing. (See 
Format of the Field Control Word and the 5250 data stream documentation for details.) 


States and Modes 


The display station can be in one of several states (conditions), each with its accompanying modes 
(methods of operation). The following is a list of these states and their associated modes: 


e Hardware error state 

e@ Normal locked state 

e Normal unlocked state 
o Command mode 
oO Insert mode 
o Data mode 

Power-on state 

Prehelp error state 

Post-help error state 


System services (SS) message state 


System request state 


See the 5250 data stream documentation for a detailed explanation of each state and mode. 


Dumping the 5250 Data Stream Commands 


If you wish to produce a dump of the 5250 data stream commands that are produced by the DSM APIs, you 
should create a physical file (using the CRTPF command) having a record length of 2000. Name the 
physical file QSNDEBUGF, and ensure that the QSNDEBUGF file exists in the library list. DSM will 
dump the 5250 data stream commands to that file. 
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Window Services APIs 


The window services APIs consist of two functional groups: the window builder and window manager 
services. The window builder APIs provide the services needed to create, delete, move, and resize 
windows. The window builder services include the window manipulation and query APIs, and the window 
I/O APIs. The window manager APIs provide the services needed to manage multiple windows, support 
I/O to several active windows, and switch between windows. 


Window Services APIs include: 


e Window Manipulation and Query APIs 


e Window I/O APIs 


e@ Window Manager Services APIs 


See Using Window Services APIs for additional information. 
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Using Window Services APIs 


A window is created using a window and a low-level environment description. The window description 
provides the window attributes, a pointer to data that is specified by the using application, and several exit 
routines that the window module calls when a window is moved, resized, or deleted so the using program 
can perform the appropriate actions. The low-level environment description is the same as that used on the 
Create Low-Level Environment (QsnCrtEnv) API to create a low-level environment. A window is 
implemented as a low-level environment where the user data pointer describes the window itself. Thus, a 
window can be manipulated through the low-level APIs or through the window APIs by using the same 
window handle. This implementation is similar to the concept of inheritance in object-oriented 
programming languages. DSM window support uses graphical user interface (GUI) when the underlying 
control unit supports it. 


Each window has the low-level environment window mode enabled. The low-level environment window 
area is set to the usable area in the window, which consists of the area inside the border and attributes that 
can be accessed by screen I/O services. (It does not include the message line.) Use relative coordinates 
when specifying a row and column on an I/O API. The upper left corner of the usable area is (1,1). To use 
absolute coordinates with a window, disable the low-level environment window mode with the Set 
Low-Level Environment Window Mode (QsnSetEnvWinMod) API. 


Figure 1 shows the components of a DSM window. The window in this example has a specified depth of 13 
rows and a width of 19 columns. 


The attributes of a DSM window are similar to those of a data description specifications (DDS) window. 
The initial size and location of a DSM window are specified using the location of the upper-left window 
border character and the number of rows and columns within the window. For DSM windows, the leading 
window attribute, right continuation attribute, or message line can be specified separately. Unlike a DDS 
window, a DSM window does not require the following: 


e A border 


If a window is defined with no border, no extra space is used on the display for the border 
characters or their attributes (L and B in Figure 1). An area of the screen is cleared starting from the 


specified location for the upper left corner of the window and continues for the number of rows and 
columns given as the window size. Figure 2 shows an example of a window with no border. 


Note: In discussions throughout the DSM sections that refer to window borders, this should be 
taken to mean the top/bottom window row or left/right window column for a window with no 
borders. 


e Window border attributes 


If a window is defined with no border attributes (L and B in Figure 1), no extra space for these is 
used on the display. Figure 3 shows a window with no border attributes. 


e Leading window attribute 


The leading window attribute (A in Figure 1) is part of the addressable window area. If specified, 


this attribute takes up an extra screen character and does not reduce the size of the window area. 
Figure 4 shows a window defined with no leading window attribute. The window text directly 


follows the window border character. Attribute characters can be written inside the window if 
desired. 


e Right continuation attribute 


If the right continuation attribute (R in Figure 1) is specified on a window description, DSM 
determines the appropriate attribute to use, based on the screen image underlying the window. If 


the window is not a GUI window, right-continuation-attribute correction is performed for 
display-screen and presentation screen DBCS-only attributes. (No correction is performed for 
extended primary attributes and DBCS data types). When a window is placed on a screen that 
supports extended attributes, all extended attributes are cleared prior to displaying the window. To 
have the right continuation attribute handle extended attributes, you must use a display that 
supports GUI windows and specify GUI window support on the window description. 


e Message line 


Specifying a message line on a window description decreases the number of lines in the window 
area by 1, as shown in Figure 1. 


Figure 1. DSM Window Layout 
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Figure 2. DSM Window with No Border 
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Figure 3. DSM Window with No Border Attributes 
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Figure 4. DSM Window with No Leading Window Attribute 
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Window Manipulation and Query APIs 


The window manipulation and query APIs are: 


Change Window (QsnChgWin) changes the description for a window. 


Create a Window (QsnCrtWin) creates a window. 


Initialize Window Description (QsnInzWinD) initializes a window description with default values. 


Move Window (QsnMovWin) moves a window to a new screen location. 


Move Window by User (QsnMovWinUsr) moves a window to a new screen location specified by 
the user. 


Resize Window (QsnRszWin) changes the size of a window. 


Resize Window by User (QsnRszWinUsr) changes the size of a window according to 
user-specified cursor movements. 


Retrieve Window Data (QsnRtvWinDta) returns a pointer to the user data for the given window. 


Retrieve Window Description (QsnRtvWinD) retrieves a copy of the description for a window. 


Set Window Services Attributes (QsnSetWinAtr) sets the default attributes for the window 
services. 
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Change Window (QsnChgWin) API 


Required Parameter Group: 


Window handle Binary(4) 
Window description Char(*) 


Length of window Binary(4) 
description 


Omissible Parameter: 
4 Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Change Window (QsnChgWin) API changes the window description for the given window. The size 
cannot be changed for a window that contains DBCS data. 


Authorities and Locks 


Exit Routine Authority 
*EXECUTE 


Required Parameter Group 


Window handle 
INPUT; BINARY(4) 


A handle for the window that will have its description changed. 
Window description 
INPUT; CHAR(*) 


The new window description for the given window. The format of the window description is shown 
in Format of the Window Description. 


Length of window description 
Input; BINARY(4) 


The length of the window description parameter. 


Omissible Parameter 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A1 E Window description value is incorrect. 
CPFA3AA E Window handle incorrect. 


API Introduced: V2R3 
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Create a Window (QsnCrtWin) AP 


Required Parameter Group: 


1 Window description Char(*) 


2 Length of window Binary(4) 
description 


Omissible Parameter Group: 


User extension information Char(*) 


Length of user extension Binary(4) 
information 

Start window Char(1) 
Low-level environment Char(*) 
description 

Length of low-level Binary(4) 
environment description 


Window handle Binary(4) 
Error code Char(*) 


Returned Value: 
Window handle Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Create a Window (QsnCrtWin) API creates a window and returns a handle for that window. The 
window must be deleted using the Delete Low-Level Environment (QsnDItEnv) API. Whenever a window 
is made current, the window mode is set to the usable area of the window. 


Authorities and Locks 


Exit Routine Authority 
*EXECUTE 


Required Parameter Group 


Window description 
INPUT; CHAR(*) 


The window description defines the attributes for the window. The format of the window 
description is shown in Format of the Window Description. 


Length of window description 
INPUT; BINARY(4) 


The length of the window description parameter. 


Omissible Parameter Group 


User extension information 
INPUT; CHAR(*) 


The user extension information is used to associate data and exit routines with the window. This 
parameter is required if the length of user extension information parameter is supplied. This 
essentially enables the object-oriented programming concept of inheritance, allowing the window 
to be extended in a natural way. The user extension information cannot be changed once the 
window has been created. The format of this parameter is shown in Format of the Window User 


Extension Information. 


Length of user extension information 
INPUT; BINARY(4) 


The length of the user extension information parameter. 
Start window 
Input; CHAR(1) 


Whether the window should be displayed on the screen when it is allocated. The possible values 
are: 


0 The window is not displayed on the screen when it is allocated. You must use the Start a 
Window (QsnStrWin) API to start the window. 


I The window is displayed on the screen when it is allocated. This is the default if this parameter 
is omitted. 


Low-level environment description 
INPUT; CHAR(*) 


The low-level environment description defines the operating environment for low-level operations 
used to create and manipulate the window. This parameter is required if the length of the low-level 
environment description parameter is supplied. The format of the low-level environment 
description is shown in Format of the Low-Level Environment Description. If this parameter is 


omitted, a low-level environment will be created with default values. 


Length of low-level environment description 
INPUT; BINARY(4) 


The length of the low-level environment description parameter. 
Window handle 
OUTPUT; BINARY(4) 
The variable containing the handle for the window created after the QsnCrtWin API has completed. 


This handle can be used across activation groups if the activation group in which the handle was 
created is still active. 


Error code 
1V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Window handle 
OUTPUT; BINARY(4) 


This API returns the value for the window handle parameter or a -1 if an error occurred during 
processing. 


Restrictions 


Windows where the associated low-level environment indicates DBCS support cannot be resized. GUI 
windows must fit within the screen boundary. This includes the leading left border attribute and the center 
border continuation attribute. GUI windows must have a border and the associated left and center border 
attributes for the left and center borders. The concept of current and noncurrent window border attributes 
does not apply to GUI windows. No error-checking is performed for GUI-specific fields. The fields are 
passed to the control unit, as specified, and any errors will be detected by the control unit. 


Format of the Window Description 


| Offset 
| D Hex |Type Field 
BINARY(4) Row location of upper left corner of window 
border 
BINARY(4) Column location of upper left corner of window 
border 


[BINARY(4) [BINARY(4) [Number of rows within the window of [Number of rows within the window within the window 


a Le ARY(4) Number of columns within the window 
| 16 10 =|BINARY(4) Minimum number of rows within the window 


20 14. |BINARY(4) Minimum number of columns within the 
window 


| 24 18 |BINARY(4) Maximum number of rows within the window 


1C_ |BINARY(4) Maximum number of columns within the 
window 


i |CHAR(1) |Full- screen flag for the window 


CHAR@G) Window display attributes for a monochrome 
display 


[ 53 [| 35 |CHAR() — |Flagbytel(GUIonlyy 


Field Descriptions 


In the following descriptions, the default value refers to the value set by the Initialize Window Description 
(QsnInzWinD) API. 


The GUlI-only fields in the following descriptions refer to fields within the data stream for the Create 
Window command major and minor structures. See the 5494 Remote Control Unit Functions Reference, 
SC30-3533, manual for details. 


Border attributes flag for the window. Whether or not the window border has left and center border 
attributes. (See Figure 10.) The possible values are: 
0 Window border has no attributes. 


1 Window border has attributes. This is the default. 


For GUI windows, | must be specified. 


Border flag for the window. This flag indicates whether or not the window has a border. (See Figure 10.) 
The possible values are: 


0 Window has no border. 
1 Window has a border. This is the default. 


If this field is set to 0, the border attributes are not written to the screen, regardless of the values of the other 
fields. 


For GUI windows, | must be specified. 


Border flags (GUI only). Determines if border presentation characters are used (byte 3 of the border 
presentation minor structure of the GUI Create Window command). The default is X'80". 


Bottom border character. The character used for the bottom border. The default is X'00' for all border 
characters. The default border character used for non-GUI windows is '.'. For GUI windows, the default 
GUI character is used. 


Color title attribute. The display attribute to precede the title on a color display. The default is X'20'. If 
this attribute is not valid, it is ignored. 


Column location of upper left corner of window border. The column number of the upper left corner of 
the window. If the window has a leading window attribute, the first window column is two greater than the 
value specified in this field; otherwise, it is one greater. This must be a positive integer value greater than or 
equal to 0. For GUI windows, the minimum value must be 2. Otherwise, it must be a positive integer value 
greater than or equal to 0. For non-GUI windows, if 0 or 1 is specified, the left border of the window or the 
leading border attribute, respectively, will not be displayed on the screen unless the window is moved. The 
default value is such that the maximum-sized window will be displayed, with border and attributes, given 
the other window description attributes (for example, window border attributes). If the window is a 
full-screen window, this field is ignored. 


Flag byte 1 (GUI only). Byte 5 of the GUI Create Window command major structure. The default is X'00'. 
Flag byte 2 (GUI only). Byte 6 of the GUI Create Window command major structure. The default is X'00'. 


Full-screen flag for the window. Indicates whether or not this is a full-screen window. (A full-screen 
window cannot be moved or resized.) The possible values are: 


0 Window is not a full-screen window. This is the default. 


1 Window is a full-screen window. 


GUI support flag for the window. This flag indicates whether or not GUI support should be used to build 
the window if the underlying device supports it. GUI windows always include a leading and trailing border 
attribute. The possible values are: 


0 Do not use GUI support. 
I Use GUI support if the underlying device supports it. This is the default. 


Leading attribute flag for the window. This flag indicates whether or not the window has a leading 
attribute. (See Figure 10.) The possible values are: 

0 Window has no leading attribute byte. 

I Window has a leading attribute byte. This is the default. 


For GUI windows, | must be specified. 


Left border character. The character used for the left border. The default is X'00' for all border characters. 
The default border character used for non-GUI windows is ':'. For GUI windows, the default GUI character 
is used. 


Length of title text. The length of the title text. The default value is 0. 


Lower left border character. The character used for the lower left border. The default is X'00' for all 
border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the 
default GUI character is used. 


Lower center border character. The character used for the lower center border. The default is X'00' for all 
border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the 
default GUI character is used. 


Maximum number of columns within the window. A value of 0, which is the default, indicates this value 
is the same as the maximum number of columns for the device in its current mode. If the window is a 
full-screen window, this field is ignored. 


Maximum number of rows within the window. A value of 0, which is the default, indicates this value is 
the same as the maximum number of rows for the device in its current mode. If the window is a full-screen 
window, this field is ignored. 


Message line flag for the window. This flag indicates whether or not the window has a message line. (See 
Figure 10). The possible values are: 


0 Window does not have a message line 


I Window has a message line. This is the default. 


Minimum number of columns within the window. The minimum value allowed is 1. This is the default. 
If the window is a full-screen window, this field is ignored. 


Minimum number of rows within the window. The minimum value allowed is 1. This is the default. If 
the window is a full-screen window, this field is ignored. 


Monochrome title attribute. The display attribute to precede the title on a monochrome display. The 
default is X'20'. If this attribute is not valid, it is ignored. 


Number of columns within the window. The number of columns in the window, from the first window 
column to the last. This excludes the left and center border, and the border and window attributes. (See 
Figure 10.) A value of 0, which is the default, indicates this value is the maximum number of columns that 
can be defined given the other window description attributes (for example, window border attributes). The 
minimum allowed number of columns is 1. If the window is a full-screen window, this field is ignored. 


Number of rows within the window. The number of rows in the window, from the first window row to the 
last. This includes the message line, if specified. (See Figure 10.) A value of 0, which is the default, 
indicates this value is the maximum number of rows that can be defined given the other window description 
attributes (for example, window message line). The minimum allowed number of rows is 1. If the window 


is a full-screen window, this field is ignored. 
Offset to title text. The offset for the window title text. The default value is 0. 


Center border character. The character used for the center border. The default is X'00' for all border 
characters. The default border character used for non-GUI windows is ':'. For GUI windows, the default 
GUI character is used. 


Center continuation attribute flag for the window. Whether or not the window has a center continuation 
attribute (see Figure 10). The possible values are: 


0 Window has no center continuation attribute byte. 


ZI Window has a center continuation attribute byte. This is the default. For GUI windows, 1 must be 
specified. 


The center continuation attribute used is X'20', which is green for color displays and normal attribute for 
monochrome displays. 


Row location of upper left corner of window border. The row number of the upper left corner of the 
window. The first window row is one greater than the value specified in this field. This must be a positive 
integer value greater than or equal to 0. For GUI windows, the minimum value must be 1. Otherwise, it 
must be a positive integer value greater than or equal to 0. For non-GUI windows, if 0 is specified, the top 
border of the window will not be displayed on the screen unless the window is moved. The default value is 
such that the maximum-sized window will be displayed, with border and attributes, given the other window 
description attributes (for example, window border attributes). If the window is a full-screen window, this 
field is ignored. 


Title text. The text for the window title, which is written in the top border of the window. If the title text is 
too long to fit in the window border, it is truncated. Otherwise, it is centered in the window border. You can 
add padding (extra blanks beside the text) to specify left or center justification for the title. If an attribute is 
specified for the title text, the window border attribute is placed after the title text. This field is ignored if 
the window does not have a top border. 


The default is no title text. 


Top border character. The character used for the top border. The default is X'00' for all border characters. 
The default border character used for non-GUI windows is '.'. For GUI windows, the default GUI character 
is used. 


Upper left border character. The character used for the upper left border. The default is X'00' for all 
border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the 
default GUI character is used. 


Upper center border character. The character used for the upper center border. The default is X'00' for all 
border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the 
default GUI character is used. 


Window display attributes for a color display. The window display attributes for a color display. The 
first character is the attribute for the window border when the window is not current, the second for when 
the window is current, and the third for the leading window attribute. All bytes may contain the same value. 
The special value X'00' can be used to indicate that no screen attribute should be used for the given 
character. The first attribute is ignored for GUI windows, which only use the second attribute. If X'00' is 
specified as the second attribute for a GUI window, the default GUI border attribute will be used. Both the 
current and noncurrent border attributes must be either X'00' or a valid attribute. For example, it is incorrect 
to specify the current attribute field X'00' and the noncurrent attribute field with a valid attribute. 


The default values for these fields are those specified by the window services mode description (see Format 


of the Window Services Attribute Description). 


Window display attributes for a monochrome display. The window display attributes for a monochrome 
display. The first character is the attribute for the window border when the window is not current, the 
second for when the window is current, and the third is for the leading window attribute. All bytes may 
contain the same value. The special value X'00' can be used to indicate that no screen attribute should be 
used for the given character. The first attribute is ignored for GUI windows, which only use the second 
attribute. If X'00' is specified as the second attribute for a GUI window, the default GUI border attribute 
will be used. Both the current and noncurrent border attributes must be either X'00' or a valid attribute. For 
example, it is incorrect to specify the current attribute field X'00' and the noncurrent attribute field with a 
valid attribute. 


The default values for these fields are those specified by the window services mode description (see Format 
of the Window Services Attribute Description). 


Window title flags (GUI only). Byte 3 of the window title minor structure of the Create Window 
command. The default is X'00'. 


Format of the Window User Extension Information 


| Offset 
| Dec Hex /|Type Field 


| 0 0 PTR(SPP) User data associated with window 
16 10 |PTR(PP) Exit routine to call for Change Window 
(QsnChgWin) API 
32 20 |PTR(PP) Exit routine to call for Delete Low-Level 
Environment (QsnDItEnv) API 
User (QsnMovWinUsr), Resize Window 
(QsnRszWin), or Resize Window by User 
64 40  |PTR(PP) Exit routine for Display Window (QsnDspWin) 
API 
80 50. |PTR(PP) Exit routine for Set Current Window 
(QsnSetCurWin) API 


48 30. =|PTR(PP) Exit routine for QsnMovWin, Move Window by 
(QsnRszWinUsr) APIs 


Field Descriptions 


Exit routine for Change Window (QsnChgWin) API. This exit routine is called after the window is 
changed. If the window is redrawn, it is called after the window is redrawn. 


Exit routine for Delete Low-Level Environment (QsnDItEnv) API. The exit routine to call when a 
window is deleted using the Delete Low-Level Environment (QsnDItEnv) API. 


Exit routine for Display Window (QsnDspWin) API. The exit routine to call immediately before the 
window is drawn or redrawn. The following APIs may cause the window to be redrawn: QsnCrtWin, 
QsnStrWin, QsnChg Win, QsnMovWin, QsnMovWinUsr, QsnRszWin, QsnRszWinUsr, QsnDspWin, and 
QsnSetCurWin. 


Exit routine for move or resize window APIs. The exit routine to call when window coordinates are 
changed using the QsnMovWin, Move Window by User (QsnMovWinUsr), Resize Window (QsnRszWin), 
or Resize Window by User (QsnRszWinUsr) APIs. This exit routine is called after the window is redrawn. 


Exit routine for Set Current Window (QsnSetCurWin) API. The exit routine to call whenever a window 
is made current by one of the following APIs: QsnCrtWin, QsnStrWin, or QsnSetCurWin. This exit routine 
is called after the window is drawn or redrawn. 


User data associated with window. A pointer to any data that the user wants to associate with this 
window. 


Window Exit Routines 


Exit routines are user-supplied functions with a defined interface. The routines are called from certain APIs 
and allow the programmer to attach additional function to those APIs. For instance, if fields have been set 
up in a window, a Change Coordinates exit routine could be supplied to move the fields if the window is 
moved. 


Exit Routine Error Handling 


If an exception occurs during the processing of an exit routine, the exception is ignored and processing 
continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an 
exit routine by adding an exception handler to the routine. 


Change Window Exit Routine 


This exit routine, if specified on the user extension information, is called when the window is changed. The 
following parameter is passed to the exit routine: 


Parameter Passed to Exit Routine 


1 Window handle Input Binary(4) 


Change Window Exit Routine Parameter 
Window handle 
INPUT; BINARY(4) 


The window that was changed. 


Delete Window Exit Routine 


This exit routine, if specified on the user extension information, is called when the window is deleted. The 
following parameter is passed to the exit routine: 


Parameter Passed to Exit Routine 


1 Window handle Binary(4) 


Delete Window Exit Routine Parameter 
Window handle 
INPUT; BINARY(4) 


The window that was deleted. 


Change Window Coordinates Exit Routine 


This exit routine, if specified on the user extension information, is called when the move or resize APIs are 
called, after the window has been successfully moved or resized, but before the window is drawn on the 
screen. For this reason, you should not use this exit routine to draw anything in the window. The draw exit 
routine is called when the window is moved or resized. The following parameters are passed to the exit 
routine: 


Parameters Passed to Exit Routine 


Window handle Binary(4) 
Top border offset Binary(4) 


Left border offset Binary(4) 
Bottom border offset Binary(4) 
Center border offset Binary(4) 


Change Window Coordinates Exit Routine Parameters 
Window handle 
INPUT; BINARY(4) 


The window for which the coordinates were changed. 
Top border offset 
INPUT; BINARY(4) 


The offset, in screen rows, from the previous top window border to the current top window border 
(after the window coordinates have been changed). It can be positive, negative, or zero, depending 
on how the top window border was changed. For example, if the top border was moved down two 
rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the top row was 

not changed, this value would be 0. 


Left border offset 
INPUT; BINARY(4) 


The offset, in screen columns, from the previous left window border to the current left window 
border (after the window coordinates have been changed). It can be positive, negative, or zero, 
depending on how the left window border was changed. For example, if the left border was moved 
two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value 
would be -4, and if the left column was not changed, this value would be 0. 


Bottom border offset 
INPUT; BINARY(4) 


The offset, in screen rows, from the previous bottom window border to the current bottom window 
border (after the window coordinates have been changed). It can be positive, negative, or zero, 
depending on how the bottom window border was changed. For example, if the border was moved 
down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the 
bottom row was not changed, this value would be 0. 


Center border offset 
INPUT; BINARY(4) 


The offset, in screen columns, from the previous center window border to the current center 
window border (after the window coordinates have been changed). It can be positive, negative, or 
zero, depending on how the center window border was changed. For example, if the center border 
was moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, 
this value would be -4; if the center column was not changed, this value would be 0. 


Draw Window Exit Routine 


This exit routine, if specified on the user extension information, is called when the Display Window 
(QsnDspWin) API is called, before the window is drawn. Because the exit routine is called before the 
window is drawn, you should only write inside the window using the command buffer parameter. Direct 
operations should not be used for the exit routine. The following parameters are passed to the exit routine: 


Parameters Passed to Exit Routine 


1 Window handle Binary(4) 
2 Command buffer Binary(4) 


Draw Window Exit Routine Parameters 
Window handle 
INPUT; BINARY(4) 


The window to be drawn. 
Command buffer 
INPUT; BINARY(4) 
The command buffer used to store the commands that re-create the window contents. The contents 


of the command buffer are written to the screen along with the window border. This allows the 
window and its contents to be redrawn in a single I/O operation. 


Current Window Exit Routine 


This exit routine, if specified on the user extension information, is called when the window is made current 
through the Set Current Window (QsnSetCurWin) API. The following parameter is passed to the exit 
routine: 


Parameter Passed to Exit Routine 


Window handle Binary(4) 


Current Window Exit Routine Parameter 
Window handle 
INPUT; BINARY(4) 


A handle for the window that is made current. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA318 E Error calling exit routine. 

CPFA327 E Low level environment description value incorrect. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A1 E Window description value is incorrect. 
CPFA3AB E The value for &1 must be '0' or'T’. 


Additional errors may be generated by this API. They are listed in Error Messages under the Create 


Low-Level Environment (QsnCrtEnv) API. 
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Initialize Window Description (QsninzWinD) API 


Required Parameter Group: 


1 Window description Char(*) 


2 Length of window Binary(4) 
description 


Omissible Parameter: 
3 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


ThelInitialize Window Description (QsnInzWinD) API initializes a window description with default values. 
Unless otherwise specified in the window description (see Format of the Window Description), pointer 
fields are set to the null pointer, numeric fields to 0, character flag fields to 0, and other character fields to 
blanks. For example, the default value for the border flag is 1, so this field will be set to 1. 


Authorities and Locks 


Exit Routine Authority 
*EXECUTE 


Required Parameter Group 
Window description 
OUTPUT; CHAR(*) 


The window description to be initialized. 
Length of window description 
INPUT; BINARY(4) 


The length of the window description parameter. 


Omissible Parameter Group 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 
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Move Window (QsnMovWin) API 


Required Parameter Group: 


1 Window handle Binary(4) 
2 Upper left row Binary(4) 
3. Upper left column Binary(4) 


Omissible Parameter: 


4 Error code 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The QsnMovWin API moves the window to the new upper left coordinate (upper left row, upper left 
column) specified. If the window can fit within the display at the location specified, it is moved to the new 
position. If a Change Window Coordinates exit routine is specified on the window description, it is called 
after the window is successfully moved. If the window is a full screen window, the API will complete 
successfully, but the window will not be moved. 


Authorities and Locks 


None 


Required Parameter Group 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be moved. 
Upper left row 
INPUT; BINARY(4) 


The absolute screen row for the new upper left corner of the window. 


Upper left col 


INPUT; BINARY(4) 


The absolute screen column for the new upper left corner of the window. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A2 E Window does not fit on screen. 

CPFA3A4 E Specified window is not active. 

CPFA3AA E Window handle incorrect. 
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Move Window by User (QsnMovWinUsr) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Move Window by User (QsnMovWinUsr) API allows a window to be moved on the screen to a new 
location specified by the user. The API positions the cursor at the upper left corner of the window and 
prompts the user to move the cursor to the new position for the upper left corner. The prompt is displayed 
only if a message line has been defined. If the window can fit within the display at the location specified, it 
is moved to the new position. If a Change Window Coordinates exit routine is specified on the window 
description, it is called after the window is successfully moved. If the window is a full screen window, the 
API will complete successfully, but the window will not be moved. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be moved. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A4 E Specified window is not active. 

CPFA3AA E Window handle incorrect. 
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Resize Window (QsnRszWin) API 


Required Parameter Group: 


1 Window handle Binary(4) 
2 Number of rows Binary(4) 
3. Number of columns Binary(4) 


Omissible Parameter: 
4 Error code 
Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Resize Window (QsnRszWin) API allows a window to be resized. If a Change Window Coordinates 
exit routine is specified on the window description, it is called after the window is successfully resized. If 
the window is a full screen window, the API will complete successfully, but the window will not be moved. 
Windows where the associated low-level environment indicates DBCS support cannot be resized. 


Authorities and Locks 


None 


Required Parameter Group 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be resized. 
Number of rows 
INPUT; BINARY(4) 


The new value for the number of rows in the window. 
Number of columns 
INPUT; BINARY(4) 


The new value for the number of columns in the window. 


Omissible Parameter 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA318 E 
CPFA31E E 
CPFA340 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3A2 E 
CPFA3A4 E 
CPFA3A5 E 
CPFA3AA E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Error calling exit routine. 

Required parameter &1 omitted. 

Operation not supported with double-byte data. 
Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Window does not fit on screen. 

Specified window is not active. 

Window dimensions not within window limits. 


Window handle incorrect. 
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Resize Window by User (QsnRszWinUsr) API 


Required Parameter: 

1 Window handle Binary(4) 
Omissible Parameter: 

2 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Resize Window by User (QsnRszWinUsr) API allows a window to be resized according to the cursor 
movements specified by the user. If the cursor is located on a border when this API is called, then that 
border can be moved. If the cursor is located on a border corner, the two sides that meet at that corner can 
be moved. If the user positions the cursor to a new row/column for the horizontal or vertical border, the 
border is moved to the new coordinate position and the window is resized accordingly. If the cursor is not 
on the border when the API is called, then the cursor is moved to the bottom center corner of the window 
and the user is prompted to move the cursor to the new position for the bottom center corner of the window. 
The prompt is displayed only if a message line has been defined. If the window is a full screen window, the 
API will complete successfully, but the window will not be moved. 


A window can be made only as small (large) as the minimum (maximum) size allowed for the window. If 
the user moves the cursor such that the resulting window will be smaller (larger) than the minimum 
(maximum) size allowed, the resulting window will be the minimum (maximum) size. If a Change Window 
Coordinates exit routine is specified on the window description, this routine is called after the window is 
successfully resized. Typically, this API would be called after the user presses a particular function key. 
Windows where the associated low-level environment indicates DBCS support cannot be resized. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be resized. 


Omissible Parameter 
Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A4 E Specified window is not active. 

CPFA3AA E Window handle incorrect. 
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Retrieve Window Data (QsnRtvWinDta) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter Group: 


2 User data pointer PTR(SPP) 
3 Error code Char(*) 


Returned Value: 


User data pointer PTR(SPP) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Window Data (QsnRtvWinDta) API returns a pointer to the user data for the given window. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window for which the user data should be returned. 


Omissible Parameter Group 


User data pointer 
OUTPUT; PTR(SPP) 


A space pointer to the user data field supplied in the user extension information when the window 
was defined. If no user data is associated with the window, the null pointer is returned. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


User data pointer 
OUTPUT; PTR(SPP) 


This API returns the value for the user data pointer parameter, or the null pointer if an error occurs. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CI1F E Pointer is not on a 16 byte boundary. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA3AA E Window handle incorrect. 
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Retrieve Window Description (QsnRtvWinD) 
API 


Required Parameter Group: 


Window handle Binary(4) 
Window description Char(*) 


Length of window Binary(4) 
description 


Omissible Parameter: 
4 Error code Char(*) 
Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Window Description (QsnRtvWinD) API retrieves a copy of the window description for the 
given window. 


Authorities and Locks 


None 


Required Parameter Group 


Window handle 
INPUT; BINARY(4) 


A handle for the window for which the window description should be returned. 
Window description 
OUTPUT; CHAR(*) 


The window description for the given window. The format of the data returned is shown in Format 
of the Window Description Returned. 


Length of window description 
INPUT; BINARY(4) 


The length of the window description parameter. If the length is larger than the size of the receiver 
variable, the results are not predictable. The minimum length is 8. The API returns as much 
information as it can fit in this length. If the available information is longer, it is truncated. If the 
available information is shorter, the unused output is unchanged; whatever is already stored in that 
space remains there. To determine how much information the API actually returns in response to 
this call, see the bytes returned field. To determine how much information the API could return if 
space were available, see the bytes available field. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


Thestructure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Window Description Returned 


| Offset 
a c | Hex /|Type Field 


| | [BINARY(4) Bytes returned 
| 4 | 4 [BINARY(4) Bytes available 
| 8 | 8 [CHAR(*) Window description 


Field Descriptions 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


Window description. The format of the remaining data returned is shown in Format of the Window 


Description. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3C24 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA3AA E 
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Error Message Text 

Severe error while addressing parameter list. 
Length of the receiver variable is not valid. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 


Window handle incorrect. 
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Set Window Services Attributes 
(QsnSetWinAtr) API 


Required Parameter Group: 


Window services attributes Input Char(*) 
description 


Length of window service Input Binary(4) 
attributes description 


Omissible Parameter: 
3. Error code Char(*) 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Window Services Attributes (QsnSetWinAtr) API sets the default attributes for the window 
services. 


Authorities and Locks 


None 


Required Parameter Group 


Window services attributes 
INPUT; CHAR(*) 


Defines the attributes for the window services APIs. The format of the window services attributes 
description is shown in Format of the Window Services Attribute Description. 


Length of window services attributes 
INPUT; BINARY(4) 


The length of the window services attributes parameter. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Window Services Attribute Description 


| Offset 
| Dec | Hex |Type Field 


| 0 | 0 |CHAR(3) [Monochrome window display attributes 
| é) | 3 [CHAR(3) [Color window display attributes 


Field Descriptions 


Color window display attributes. The window display attributes for a color display. The first character is 
the attribute for the window border when the window is not current, the second for when the window is 
current, and the third for the leading window attribute. The first attribute is ignored for GUI windows, 
which only use the second attribute. All bytes can contain the same value. The special value X'00' indicates 
that no screen attribute is to be used for the given character. Both the current and noncurrent border 
attributes must be either X'00' or a valid attribute. For example, it is incorrect to specify the current attribute 
field X'00' and the noncurrent attribute field with a valid attribute. 


The default values for these fields are X'20' for green, X'3A' for blue, and X'20' for green. 


Monochrome window display attributes. The window display attributes for a monochrome display. The 
first character is the attribute for the window border when the window is not current, the second for when 
the window is current, and the third for the leading window attribute. The first attribute is ignored for GUI 
windows, which only use the second attribute. All bytes may contain the same value. The special value 
X'00' indicates that no screen attribute is to be used for the given character. Both the current and noncurrent 
border attributes must be either X'00' or a valid attribute. For example, it is incorrect to specify the current 
attribute field X'00' and the noncurrent attribute field with a valid attribute. 


The default values for these fields are X'20' for normal attribute, X'22' for high intensity, and X'20' for 
normal attribute, respectively. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3C1D E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3AC E 


Error Message Text 

Severe error while addressing parameter list. 
Length specified in parameter &1 not valid. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 


Window services attributes description value is incorrect. 
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Window I/O APIs 


The majority of window I/O operations are performed through calls to the low-level services interfaces. If 
specified on the window description or through an explicit call to the Set Low-Level Environment Window 
Mode (QsnSetEnvWinMod) API, the low-level interfaces can operate in a relative mode, where operations 
such as Set Field (QsnSetFld) are performed relative to the current window. See Set Low-Level 


Environment Window Mode (QsnSetEnvWinMod) API for details. 


The APIs specific to window I/O operations are: 


e Clear Window (QsnClrWin) clears the window area. 


e Clear Window Message (QsnClrWinMsg) clears the message for a given window. 


e Display Window (QsnDspWin) draws the window border and clears the window area. 


e Put Window Message (QsnPutWinMsg) puts a message on the message line for a given window. 
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Clear Window (QsnClrWin) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter: 
2 Error code Char(*) 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Clear Window (QsnClrWin) API clears the window area for the given window. Any field definitions 
remain intact. Use the Clear Field Table (QsnClrFldTbl) API to remove field definitions. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be cleared. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A4 E Specified window is not active. 

CPFA3AA E Window handle incorrect. 
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Clear Window Message (QsnClrWinMsg) API 


Required Parameter: 

1 Window handle Binary(4) 
Omissible Parameter: 

2 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Clear Window Message (QsnClrWinMsg) API clears the window message for the given window. This 
API is valid only if the window has a message line specified for it. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window containing the message to be cleared. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 


was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3A4 E 
CPFA3A7 E 
CPFA3AA E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Specified window is not active. 

Window does not have a message line. 


Window handle incorrect. 
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Display Window (QsnDspWin) API 


Required Parameter: 


1 Window handle 


Omissible Parameter: 


2 Error code 


Returned Value: 


Return code Output 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


Binary(4) 


Binary(4) 


The Display Window (QsnDspWin) API draws the window border for the current window and clears the 
window area. The QsnDspWin API does not make a window current. It simply redraws the window using 
the existing border attributes. For overlapping windows, use this API only for the current window. If a 
Draw Window exit routine is specified on the window description, this routine is called after the window is 
defined successfully and prior to actually drawing the window. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be drawn. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA318 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3A4 E 
CPFA3AA E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Error calling exit routine. 

Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Specified window is not active. 


Window handle incorrect. 
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Put Window Message (QsnPutWinMsg) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter Group: 


Message Input Char(*) 
Message length Input Binary(4) 
Lock keyboard Input Char(1) 
Message identifier Input Char(7) 
Qualified message file name Input Char(20) 
Row Input Binary(4) 
Column Input Binary(4) 


Starting monochrome Input Char(1) 
attribute 


Ending monochrome attribute Input Char(1) 
Starting color attribute Input Char(1) 
Ending color attribute Input Char(1) 
Error code V/O Char(*) 


2 
3 
4 
5 
6 
of 
8 
9 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Put Window Message (QsnPutWinMsg) API places an error message on the message line for the given 
window. This API is valid only if the window has a message line specified for it. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window in which the message should be placed. 


Omissible Parameter Group 


Message 
INPUT; CHAR(*) 
The message to be displayed. If the message does not fit within the window, it is truncated to fit. If 
the message length parameter is specified as nonzero, the message parameter is required. The 


message or the message ID parameter must be specified. If the message parameter is specified, the 
message ID parameter is ignored and no help key support is available for the message. 


Message length 
INPUT; BINARY(4) 


The number of bytes of message data to be displayed. 
Lock keyboard 
INPUT; CHAR(1) 


Whether the keyboard should be placed in prehelp error state of not. The possible values are: 


0 Do not place the keyboard in prehelp error state. 


I Place the keyboard in prehelp error state. If 1 is specified, the processing of this API follows 
that of the QsnSetErr API and the QsnPutWinMsg API must be followed by an 
AID-associated read API. This is the default. 


Message identifier 
INPUT; CHAR(7) 
The identifying code for the predefined message to be displayed. The first level text is displayed. If 


the user moves the cursor to the message line and presses the Help key, the message No help text 
available is displayed. This parameter is required if the message parameter is omitted. 


Qualified message file name 
INPUT; CHAR(20) 
The name of the message file from which to retrieve the message information, and the library in 


which the message file resides. This parameter is required if the message parameter is omitted. The 
format of this parameter is: 


Bytes Value 
I-10 Message file name 


11-20 Message file library. This can be an actual library name or one of the special values 
*CURLIB or *LIBL. 


Row 
INPUT; BINARY(4) 


The relative window row at which to position the cursor when the message is displayed. To move 
the cursor, the API must be followed by an AID-associated read API. 


If both row and column are omitted or specified with a zero value, the cursor is not moved. Row 
and column must both be specified or omitted; one cannot be specified if the other is omitted. 


Column 
INPUT; BINARY(4) 


The relative window column at which to position the cursor when the message is displayed. 
Starting monochrome attribute 
INPUT; CHAR(1) 


The initial screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no initial attribute is written to the display for the data. 


The monochrome and color attributes parameters are the initial and ending screen attributes: an 
initial and ending screen attribute to be used for a monochrome or a color display, respectively. 
One of these parameters will be selected based on the underlying display type, and the other will be 
discarded. Any of the attributes can be specified as a special value, X'00', indicating that no screen 
attribute should be written to the display. If the initial screen attribute is specified as an actual 
attribute, the data column, if specified, must be greater than or equal to 2. The initial screen 
attribute, if not X'00', will be written to the screen at the column previous to the first data character 
if row and column are specified, otherwise to the current display address. The ending screen 
attribute, if not X'00', will be written at the column directly after the last data character. 


See Screen Attribute Characters for a description of the screen attribute values. 
Ending monochrome attribute 
INPUT; CHAR(1) 
The ending screen attribute for monochrome displays. If this parameter is omitted and monochrome 
attributes are to be used, no ending attribute is written to the display for the data. 
Starting color attribute 
INPUT; CHAR(1) 


The initial screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no initial attribute is written to the display for the data. See Screen Attribute Characters for 


a description of the screen attribute values. 


Ending color attribute 
INPUT; CHAR(1) 
The ending screen attribute for color displays. If this parameter is omitted and color attributes are to 
be used, no ending attributes are written to the display for the data. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 


was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA307 E 
CPFA30D E 
CPFA31E E 
CPFA333 E 
CPFA335 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3A4 E 
CPFA3A7 E 
CPFA3A8 E 
CPFA3AA E 
CPFA3AB E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Screen position &1, &2 outside of display or window area. 
Invalid screen attribute. 

Required parameter &1 omitted. 

Parameter &1 not positive integer value. 
Screen address parameter error. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Specified window is not active. 

Window does not have a message line. 

Error occurred retrieving message text. 
Window handle incorrect. 


The value for &1 must be '0' or '1'. 
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Window Manager Services APIs 


The window manager services APIs manage multiple windows, support I/O to several active windows, and 
allow switching between windows. Much of the work of the window manager services is performed 
implicitly through the window builder routines. 


Windows are managed on an activation-group basis. That is, all windows that were started within a given 
activation group will be managed as a unit. You can only switch to or end a window that was started within 
the current activation group. If windows need to be redrawn, only those windows within the current 
activation group will be redrawn. A window can be created in one activation group and started in another 
group. The activation group in which the window was started will be the group to manage the window. 
The window manager services APIs are: 


e End a Window (QsnEndWin) ends an active, current window and removes it from the screen. 
e Retrieve Current Window (QsnRtvCurWin) returns the handle for the current window. 


e Set Current Window (QsnSetCurWin) makes the specified window current. 


e Start a Window (QsnStrWin) starts a window by displaying it and making it the current window. 
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End a Window (QsnEndWin) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter Group: 


2 Restore screen 
3_Error code 


Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The End a Window (QsnEndWin) API ends a currently active window that was started with the Start a 
Window (QsnStrWin) API. The window is removed from the display on the screen and from the active 
window list. The data associated with the window is not deallocated. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window to be ended. 


Omissible Parameter Group 


Restore screen 
INPUT; CHAR(1) 


Indicates if the underlying display image should be restored when the window is ended. This 


parameter is ignored if the underlying display image was not saved. This option should be used if 
the screen will be refreshed by another application and does not need to be refreshed when the 
window is removed. Performance can be improved by not restoring the display image. However, 
the saved screen may not be restored properly if it is not restored by another application. 


The possible values are: 


0 Do not restore the screen when the window is ended. 


I Restore the screen, if saved, when the window is ended. This is the default. 


Error code 


1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3A4 E 
CPFA3AA E 
CPFA3AB E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Specified window is not active. 

Window handle incorrect. 


The value for &1 must be '0' or '1'. 
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Retrieve Current Window (QsnRtvCurWin) API 


Omissible Parameter Group: 


1 Current window handle Output Binary(4) 
2 Error code V/O Char(*) 


Returned Value: 
Current window handle Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Current Window (QsnRtvCurWin) API returns the handle for the current window. 


Authorities and Locks 


None 


Omissible Parameter Group 


Current window handle 
OUTPUT; BINARY(4) 
The variable that contains the handle for the current window when the QsnRtvCurWin API has 
completed. If there is no current window, this parameter is set to 0. 
Error code 
1V/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Current window handle 
OUTPUT; BINARY(4) 


This API returns the value for the current window handle parameter. If there is no current window, 
this API returns 0. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
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Set Current Window (QsnSetCurWin) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Set Current Window (QsnSetCurWin) API makes the given window the current window. The 
QsnSetCurWin API draws the window with the current window border attribute, if specified. The Current 
Window exit routine, if specified on the window description, is called after the given window becomes 
current. The current window overlays all other windows on the display screen. 


Authorities and Locks 


None 


Required Parameter 


Window handle 
INPUT; BINARY(4) 


A handle for the window that will become current. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3A4 E Specified window is not active. 

CPFA3AA E Window handle incorrect. 
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Start a Window (QsnStrWin) API 


Required Parameter: 
1 Window handle Binary(4) 
Omissible Parameter Group: 


2 Save screen Char(1) 
3. Error code Char(*) 


Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Start a Window (QsnStrWin) API starts a window created with the Create a Window (QsnCrtWin) API. This causes 
the window to be displayed on the screen and added to the active window list. If specified, the Draw Window exit routine 
is called immediately before the window is drawn. 


Authorities and Locks 


None 


Required Parameter 
Window handle 
INPUT; BINARY(4) 


A handle for the window to be started. 


Omissible Parameter Group 


Save screen 
INPUT; CHAR(1) 


Indicates if the underlying display image should be saved prior to drawing the window. This option should be used 
only if the window will not be moved or resized over an existing display image. Performance can be improved by 
not saving the display image. However, doing this limits the overlapping nature of the window. If an attempt is 
made to move or resize a window for which the display image was not saved, the screen is cleared and all windows 
are redrawn prior to moving the window. 


The possible values for this parameter are: 


O Do not save the underlying display image when the window is started. 


I Save the underlying display image when the window is started. This is the default. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this 
parameter is omitted, diagnostic and escape messages are issued to the application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or 
-1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &amp;1 API. 
CPFA318 E Error calling exit routine. 

CPFA31E E Required parameter &amp;1 omitted. 
CPFA343 E Output operation not done. 

CPFA344 E The file &amp;2 in library &amp:;3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3AA E Window handle incorrect. 

CPFA3AB E The value for &amp;1 must be '0' or '1’. 


Performance Considerations 


You can improve the performance of window operations by doing the following: 


e Do not save or restore the underlying screen image when a window is started or ended with the Start a Window 
(QsnStrWin) or End a Window (QsnEndWin) API, respectively. See pages Start a Window (QsnStrWin) API and 
End a Window (QsnEndWin) API. 


e For non-GUI windows, use the same color for current and noncurrent boundaries. 


e Use a display station attached to a control unit that supports an enhanced interface for a nonprogrammable work 
station, even if you are not using GUI windows. 


e@ Use GUI window support when the underlying control unit supports this. 


Creating/Manipulating Windows Example 


The sample program in Figure 14 shows how to create and manipulate several windows with exit routines. The program 
creates three windows- Window 1, Window 2, and Window 3. Each time Enter is pressed, the next window is made 
current; in which case, the Draw Window exit routine for that window is called. If the user presses F4=Move or F5=Resize, 
the current window is moved or resized and the Draw Window exit routine is called again. The resulting screen output is 
shown in Figure 15. 


Figure 14. Creating and Manipulating Windows 


#include <stddef.h> 
#include <stdlib.h> 
#include <string.h> 
#include <stdio.h> 
#include "qsnapi.h" 


void GenericDraw(const Qsn_Cmd_Buf_T *cbuf, const Qsn_Win_T *win) 


{ 


char *msgl 
char *msg2 


"F3: quit F4: move F5: resize"; 
"text no attribute"; 


QsnWrtDta(msg2, strlen(msg2), 0, 2, 1, QSN_NO_SA, QSN_NO_SA, 
QSN_NO_SA, QSN_NO_SA, *cbuf, *win, NULL); 

QsnWrtDta(msgl, strlen(msgl), 0, -1, 1, OSN_SA_HI, QSN_SA_NORM, 
QSN_SA_RED, QSN_SA_ NORM, *cbuf, *win, NULL); 


} 


void Drawl (const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) 
{ 


char *txt = "window 1 (ul/blue)"; 


GenericDraw(cbuf, win); 
QOsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_ UL, QSN_SA_NORM, 
QSN_SA_ BLU, QSN_SA_ NORM, *cbuf, *win, NULL); 


} 


void Draw2(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) 
{ 


char *txt = "window 2 (ul/red)"; 


GenericDraw(cbuf, win); 
QOsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM, 
QSN_SA_ RED, QSN_SA_ NORM, *cbuf, *win, NULL); 


} 


void Draw3(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) 
{ 


char *txt = "window 3 (ul/pink)"; 


GenericDraw(cbuf, win); 
QOsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM, 
QSN_SA_ PNK, QSN_SA_ NORM, *cbuf, *win, NULL); 
} 
int main (void) { 
int i; 
char text[100]; 
Qsn_Win_T winl, win2, win3, cur; 
Qsn_Win_Desc_T win_desc; 
Qsn_Win_Ext_Inf_T ext = { NULL, NULL, NULL, NULL, NULL, NULL }; 
Q Bin4 win_desc_length = sizeof (win_desc) ; 
char aid; 


QOsnInzWinD (&win_desc, 


win_desc 


win_desc_length, NULL); 


-GUI_support = '0'; 


/* define and start window 1 */ 


win_desc 
win_desc 
win_desc 
win_desc 


ext .draw_fp 


winl 


QsnGetAID (NULL, 


.top_row 33 
-left_col = 5; 
.num_rows 13; 


-num_cols 


40; 


Drawl; 

QOsnCrtWin (&win_desc, 
MIs, 
0, 


win_desc_length, sizeof (ext), 


0, NULL, NULL); 


&ext, 
NULL, 
NULL) ; 


/* define and start window 2 */ 


win_desc 
win_desc 
win_desc 
win_desc 


ext .draw_fp 
win2 = QsnCrtWin(&win_desc, 
ua RL 


QsnGetAID(NULL, O, 


.top_row 


-left_col = 


.num_rows 
-num_cols 


L017 
10; 
10; 
30; 


Draw2; 


win_desc_length, sizeof (ext), 


0, NULL, NULL); 


&ext, 
NULL, 
NULL) ; 


/* define and start window 3 */ 
-top_row = 5; 


win_desc 
win_desc 
win_desc 
win_desc 


ext .draw_fp 


win3 


cur 


for ( 7; 
ae, ¥( 


-left_col 
.-num_rows 
-num_cols 


win3; 


){ 


( (aid=QsnGetAID (NULL, 


= 20; 
15% 
50; 


Draw3; 
OsnCrtWin (&win_desc, 
ie Mee 


win_desc_length, sizeof (ext), 


0, NULL, NULL); 


&ext, 
NULL, 


0, NULL)) == QSN_F3) ) 


break; 
else if (aid == QSN_F4) 

QsnMovWinUsr (cur, NULL); 

else if (aid == QSN_F5) 

QsnRszWinUsr (cur, NULL); 

else { 

/* switch current window to next window */ 

if (cur == winl) { 
QsnSetCurWin(win2, 
cur win2; 

} else if (cur == win2) { 
QsnSetCurWin(win3, NULL); 
cur win3; 

} else { 
QsnSetCurWin(winl, 
cur winl; 


NULL) ; 


NULL) ; 


Figure 15. Display Screen 


Command | 
RCHASDOI 
Request level: 


text no attribute 
window 1 


window 3 (ul/pink) 


quit F4: move F5: resize 


F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages 
F1l1l=Display full F12=Cancel F13=Information Assistant F24=More 
keys 
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Session Services APIs 


The session services APIs provide a general scrolling I/O interface. They can be used to build a standard 
input-line scrolling interface or an interface that has an output-only scroll area (called a scroller) in a 
window. Sessions are special cases of windows as supported by the window services. A session is defined 
using a session, a window, and a low-level environment description. The window and low-level 
environment descriptions are the same as those used to define a window directly with the window services 
APIs. The session description defines the structure of the session. The structure includes the coordinates of 
the scrolling portion, the length of the input line, the amount to roll by, and so on. A session is implemented 
as a window, where the window user data pointer describes the session itself. Thus, a session can be 
manipulated through the window and low-level interfaces by passing the session handler or through the 
session interfaces. This implementation is similar to the concept of inheritance in object-oriented 
programming languages. 


Sessions are similar in concept to subfiles and can be used for any application that requires a scrolling line 
interface. The session services APIs are divided into the following functional groups: 


e Session manipulation and query APIs allow you to create, query, and manipulate sessions. 


e Session I/O APIs allow you to perform input and output operations to sessions. 


For additional information, select one of the following: 


e Session Details 


e Line Mode and Character Mode I/O 


e Command Key Action Routines 


e Action Routine Parameters 


e Active Position 


e EBCDIC Display Control Characters 
e DBCS Considerations 
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Using Session Services APIs 


Session Details 


The following figure shows the default attributes provided by the DSM session description for a session. 


Session Attributes 


7| =! SCROLLER | 


15 | : F3=Exit F6=Print F9=Retrieve : 


16| : F14=Move F15=Resize F22=Switch 


The main component of a session is the scrollable area, or scroller, where output data can be displayed for the session. A 
session may or may not have a data input line, depending on the application. A session that uses the default attributes has 
an input line underneath the scroller. You can allow the size and location of the session attributes to default based on the 
window size, or you can specify these explicitly. Up to two lines of command key descriptions can appear below the 
scroller and can be managed by a session. For details on the session description see Create a Session (QsnCrtSsn) API. 


When a window containing a session is moved or resized, the scroller and any automatically defined fields are redrawn to 
reflect the new window positions and size. If any additional items have been added to the session through the low-level 
interface APIs, you must supply an exit program that will reposition such items explicitly. See Create a Session 


(QsnCrtSsn) API for details on the exit program. 


Line Mode and Character Mode I/O 


Session I/O can be performed in a line mode or a character mode basis. In line mode, each call to the line-specific 
interfaces operates on a complete line, either on input or output. In character mode, I/O is performed a character at a time. 
This means that multiple I/O operations can be issued to operate on the current line. For example, an output operation 
could output several characters. Then a backspace operation could be followed by input from the current cursor position. 
(All input operations are still performed in block mode, where the input is not available until an AID-generating key has 
been pressed.) 


Line mode output is performed using the Write Line to Scroller (QsnWrtSclLin) API. This API writes a line of data to the 
next session line and sets the active position (see Active Position) to the start of the next line after the added line. For 
character output, the Write Characters to Scroller (QsnWrtSclChr) API is used. This API outputs a string of characters 
starting at the active position. After this operation completes, the active position is one position past the last character 
written, or it is the position specified by a control character sequence if this appears at the end of the data. 


Command Key Action Routines 


Part of the session description is an array of command key actions. Each action is an exit routine that is specified as a 
function pointer. When a command key is pressed during a QsnReadSsnDta operation, if an action has been specified, the 
appropriate exit routine is called. Otherwise, an Invalid key pressed error message will be issued. DSM provides a group 
of functions that can be called, or user-defined exit-routines can be specified. The action routines are specified as an array 
of 24 function pointers in the session description. (See Create a Session (QsnCrtSsn) API for details.) The default values 
for the action routines DSM calls are: 


Cmd Key Action Routine 


1 

2 

3 

4 

5 

6 Print Scroller Data (QsnPrtScl) 

7 Roll Scroller Down (QsnRollScIDown) 

8 Roll Scroller Up (QsnRollSclUp) 

9 Retrieve Session Input Line to Input Line (QsnRtvSsnLin) 
10 

Il Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) 


12 

13 

14 Move Window by User (QsnMovWinUsr) 
IS Resize Window by User (QsnRszWinUsr) 
16 

17 Display Scroller Top (QsnDspSclT) 

18 Display Scroller Bottom (QsnDspSclB) 
19 Shift Scroller Left (QsnShfSclL) 

20 Shift Scroller Right (QsnShfSclR) 

21 Display Command Line Window (direct mapping to QUSCMDLN API) 
22 

23 

24 


The default action routines for command keys 7, 8, 19, and 20 (QsnRollScIDown, QsnRollSclUp, QsnShfSclIL, and 
QsnShfSclR, respectively) will pass any numeric input to the API when the command key is pressed. For example, to 
shift the scroller to the right by 10 columns, the value 10 could be entered at the input line prior to pressing command key 
20. Non-numeric input is ignored. 


When a user-defined action routine is called, it is passed the following information: 


Information Passed to the Action Routine 


1 Session handle Input Binary(4) 


2 Input buffer Input Binary(4) 
3 Returned action Output Char(1) 


When the specified command key is pressed, the action routine for the command key is called. If you change the default 
values to have a command key call a different DSM API, you cannot specify the API directly because the action routine is 
passed specific parameters. You must define an action routine that can accept the action routine parameters and then call 
the desired DSM API with the appropriate parameters. You can define a generic action routine that is specified for each 
key you want to define, and in that action routine query the input buffer to determine the command key pressed and the 
appropriate action to take. 


When an action routine is called, any data on the input line will remain. You can use the QsnWTD API to clear the line. 
However, if you write to the session or perform any action that causes the session to be redrawn in the action routine, the 
data on the input line will be lost. 


If an exception occurs during the processing of an action routine, it is ignored and processing continues. A CPFA3D9 will 
be issued as an exception from the QsnReadSsnDta API when control returns from the action routine. You can handle 
exceptions explicitly by adding an exception handler to the action routine. 


Action Routine Parameters 


Session handle 
INPUT; BINARY(4) 


The session currently active. If the action routine causes the active session to change, this variable will be 
changed to reflect the new session. 


Input buffer 
INPUT; BINARY(4) 


The input buffer containing the results of the input operations that caused this exit routine to be called. The input 
buffer can be queried using the low-level interface routines. This is the buffer that was passed to QsnReadSsnDta. 


Returned action 
OUTPUT; CHAR(1) 


The variable containing the flag indicating if, following a successful return from this exit routine, control returns 
to the caller of the Read Data from Session (QsnReadSsnDta) API or if QsnReadSsnDta handles the next input 
operation. If an error occurs in the exit routine, control always returns to the caller. The possible values are: 


O QsnReadSsnDta continues to handle the next input operation. Control does not return to the caller. 


ZI QsnReadSsnDta returns control to the caller. The output parameters for QsnReadSsnDta are filled in 
appropriately. 


Active Position 


The active position in the scroller is the point at which data will be written for character mode operations. The active 
position is affected by output operations to the scroller, including the writing of data that contains EBCDIC display 
control character sequences. 


EBCDIC Display Control Characters 


The data written to the scroller may contain display control characters consisting of single byte EBCDIC values. If 
specified on the session description (see Create a Session (QsnCrtSsn) API), the APIs for writing data to the scroller will 
check for and interpret such control characters. Each control character recognized in the output data is replaced by a call 
to a DSM API or internal routine that will perform the appropriate function. The following table shows the control 
characters that are recognized and the APIs that are called, where applicable. 


EBCDIC Display Control Characters 


(Character [Hex Value [Interpretation 
qT Jos |QsnSciTab 
vr OB. |QsnSekr SCS 
[FF foc. |QsnSciFF 
Ro |QsnSeicR SS 
INL [iS snc 
IBS [le |QsnSeBS SSCS 
BEL pF |QsnBeep 


DBCS Considerations 


If the low-level environment description (see Format of the Low-Level Environment Description) for the session specifies 
DBCS support, the session services will check for and handle DBCS data. DBCS data must be enclosed by shift control 
(SO/SD characters. The DBCS support field determines the type of the input field defined for the session, but does not 
affect the checking done for session output data other than to indicate that DBCS data may be present. The scroller does 
not display data using extended NLS attributes, regardless of the underlying display device support. 


If DBCS support is specified, the wrap indication for the session description must always be set to 1. Also, line retrieval is 
not supported for DBCS sessions. 


The QsnWrtSclChr, QsnSclIBS, QsnScICR, QsnSclFF, QsnSclLF, QsnScINL and QsnSclTab APIs are disabled for a 
DBCS session. A CPFA340 (Operation not supported with double-byte data.) will be signaled. QsnWrtSclLin is the only 
DBCS-capable session output API. 


If DBCS support is specifed, the display control characters indication of the session description (see Format of the 
Session Description) is ignored. Any EBCDIC control characters in the line of data passed to QsnWrtSclLin will be 
interpreted as shown in Table 9 - EBCDIC Display Control Characters. 
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Session Manipulation and Query APIs 


The session manipulation and query APIs are: 


Change Session (QsnChgSsn) changes the description for a session. 
Clear Scroller (QsnClrScl) clears the scroller data. 


Create a Session (QsnCrtSsn) creates a session for subsequent session I/O operations. 


Display Scroller Bottom (QsnDspSclB) shows the last line of scroller data. 


Display Scroller Top (QsnDspSclT) shows the first line of scroller data. 


Initialize Session Description (QsnInzSsnD) initializes a session description with default values. 
Query If Scroller in Line Wrap Mode (QsnQrySclWrp) queries if line wrap mode is on or off. 


Retrieve Number of Columns to Shift Scroller (QsnRtvSclNumShf) returns number of columns to 
shift scroller by. 


Retrieve Number of Rows to Roll Scroller (QsnRtvSclNumRoll) returns the number of rows to roll 
scroller by. 


Retrieve Session Data (QsnRtvSsnDta) returns a pointer to the user data for a session. 


Retrieve Session Description (QsnRtvSsnD) retrieves a copy of the description for a session. 


Roll Scroller Down (QsnRollSclDown) rolls the scroller down. 
Roll Scroller Up (QsnRollSclUp) rolls the scroller up. 

Shift Scroller Left (QsnShfSclL) shifts the scroller to the left. 
Shift Scroller Right (QsnShfSclR) shifts the scroller to the right. 


Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) toggles the session between line wrap and 
truncation mode. 
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Change Session (QsnChgSsn) API 


Required Parameter Group: 


1. Session handle Input Binary(4) 
2 Session description Input Char(*) 
3. Length of session description Input Binary(4) 


Omissible Parameter: 


4 Error code 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Change Session (QsnChgSsn) API changes the session description for the given session. If the session 
contains DBCS data, the input line or the number of columns in the scroller cannot be changed. If the 
session is currently displayed, it will be redrawn to reflect any changes. 


Authorities and Locks 


Exit Routine Authority 
*EXECUTE 


Required Parameter Group 
Session handle 
INPUT; BINARY(4) 


A handle for the session for which the session description is to be changed. 
Session description 
INPUT; CHAR(*) 


The format of the session description is shown in Format of the Session Description. 


Length of session description 


INPUT; BINARY(4) 


The length of the session description parameter. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape essages are issued to the application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA318 E Error calling exit routine. 

CPFA340 E Operation not supported with double-byte data. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3D1 E Session description value is incorrect. 
CPFA3D6 E Session handle is incorrect. 
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Clear Scroller (QsnClirScl) API 


Required Parameter: 


1 Session handle Binary(4) 


Omissible Parameter Group: 


2 Resize indication 
3_ Error code 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Clear Scroller (QsnClrScl) API clears the scroller data associated with a session and optionally resizes 
the scroller buffer. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be cleared. All data in the scroller will be cleared. 


Omissible Parameter Group 


Resize indication 
Input; CHAR(1) 


Whether the scroller buffer should be resized when it is cleared. 


0 Maintain current buffer size and data. This is the default. 


I Resize the buffer to the initial size given on the session description. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3AB E The value for &1 must be '0' or '1'. 
CPFA3D6 E Session handle is incorrect. 
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Create a Session (QsnCrtSsn) API 


Required Parameter Group: 


1. Session description Input Char(*) 
2 Length of session description Input Binary(4) 


Omissible Parameter Group: 


User extension information Input Char(*) 


Length of user extension Input Binary(4) 
information 


Start session flag Input Char(1) 
Window description Input Char(*) 


Length of window Input Binary(4) 
description 


Low-level environment Input Char(*) 
description 


Length of low-level Input Binary(4) 
environment description 


Session handle Output Binary(4) 
11 Error code 1/O Char(*) 


Returned Value: 


Session handle Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Create a Session (QsnCrtSsn) API creates a session and returns a handle for the created session. The 
session must be deleted using the Delete Low-Level Environment (QsnDItEnv) API. 


Authorities and Locks 


None. 


Required Parameter Group 


Session description 
INPUT; CHAR(*) 


The defined attributes of the session to be created. It must be declared aligned on a 16-byte 
boundary. The format of the session description is shown in Format of the Session Description. 


Length of session description 
INPUT; BINARY(4) 


The length of the session description parameter. 


Omissible Parameter Group 


User extension information 
INPUT; CHAR(*) 


Information that is used to associate data and exit routines with the session. This parameter is 
required if the user extension information length parameter is supplied. This essentially enables the 
object-oriented programming concept of inheritance, allowing the session to be extended in a 
natural way. The user extension data cannot be changed once the session has been created. The 
format of this parameter is shown in the section Format of the Session User Extension Data. 


Length of user extension information 
INPUT; BINARY(4) 


The length of the user extension information parameter. 
Start session flag 
INPUT; CHAR(1) 


Whether or not the session should be displayed on screen when it is created. The possible values 
are: 


O Do not display the session on the screen when it is created. If you specify this value, you must 
use the Start a Window (QsnStrWin) API to display the session. 


I Display the session on the screen when it is created. This is the default. 


Window description 
INPUT; CHAR(*) 


The defined attributes for the window containing the session. This parameter is required if the 
window description length parameter is supplied. The format of the window description is shown in 
Format of the Window Description. If this parameter is omitted, a window will be created with 


default values. 


Length of window description 
INPUT; BINARY(4) 


The length of the window description parameter. 


Low-level environment description 
INPUT; CHAR(*) 


operating environment for low-level operations used to create and manipulate the windows. This 
parameter is required if the low-level environment description length parameter is supplied. The 
format of the low-level environment description is shown in Format of the Low-Level Environment 


Description. If this parameter is omitted, a low-level environment will be created with default 
values. 


Length of low-level environment description 
INPUT; BINARY(4) 


The length of the low-level environment description parameter. 
Session handle 
OUTPUT; BIN(4) 


The variable containing a handle for the created session after the QsnCrtSsn API has completed. 
This handle can be used across activation groups if the activation group in which the handle was 
created is still active. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Session handle 
OUTPUT; BINARY(4) 


This API returns the value for the session handle parameter or -1 if an error occurs during 
processing. 


Format of the Session Description 


| Offset 
| Dec Hex /|Type Field 


356 TREO ate a 


| 412 | 19C [B INARY(4) [Scroller buffer maximum size 

| 416 | 1A0 [B INARY(4) [Scroller buffer increment 

| 420 | 1A4 [BIN ARY(4) [N umber of rows for input line 

| 424 | 1A8 |CHAR(1) [Reserved 

| 425 | 1A9 |CHAR( 1) [Wrap indication 

| 426 | 1AA [CHAR(1) [Reserved 

| 427 | 1AB [CHAR( 1) [Display control characters indication 
| 428 | 1AC |CHAR( 1) [Echo session input 

| 429 | 1AD [CHAR( 1) [Show scroller lines 

| 430 | 1AE [CHAR(1) [Show scroller characters 

| 431 | 1AF |CHAR( 1) [Show command key descriptions 


432 1BO |CHAR(1) Command key attribute for a monochrome 
display 


| 433 | 1B1 [CHAR(1) [Command key attribute for a color display 
| 434 | 1B2 |CHAR(1) [Input line attribute for a monochrome display 
| 435 | 1B3 [CHAR(1) [Input line attribute for a color display 

| 436 1B4 [BIN ARY(4) [Offset to input line prompt 

| 440 | 1B8 [BINARY (4) [Length of input line prompt 

| 444 | 1BC [BIN ARY(4) [Offset to command key description line 1 

| 448 1C0 [BIN ARY(4) [Length of command key description line 1 
| 452 | 1C4 [BINARY (4) [Offset to command key description line 2 

| 456 | 1C8 [BIN ARY(4) [Length of command key description line 2 
| 460 | 1CC [CHAR(20) (Reserved. 

| i | ~ |CHAR(*) [Input line prompt 

| * | * [CHAR(*) [Command key description line 1 

| 5 | ba [CHAR(*) [Command key description line 2 


Field Descriptions 


In the following descriptions, the default value refers to the value set by the Initialize Session Description 
(QsnInzSsnD) API. 


Array of command key actions. An array of 24 function pointers, each corresponding to the action to be 
performed when the associated command key is pressed. An element that is specified as a null pointer 
indicates that the command key is invalid. An element can also be set to the dummy routine 
QsnSameAction, in which case the current action routine for that key is used. If a command key action is 
set to the dummy routine QsnDefaultAction, then the default action for that key is used. The defaults for 
command key actions and the parameters passed to the action routines are described in Command Key 
Action Routines. The procedures are exported as part of the service program that contains the DSM session 
services. 


Command key attribute for a color display. The default value is X'28' for red. 


Command key attribute for a monochrome display. The default value is X'20' for normal attribute. 


Command key description line 1. The text string for the first line of command key descriptions. 
Command key description line 2. The text string for the second line of command key descriptions. 


Default number of columns to shift scroller by. The default number of columns to shift scroller by for the 
Shift Scroller left (QsnShfSclL) and Shift Scroller center (QsnShfSclR) APIs. This value must be a positive 
integer value. If 0 is specified, the default is the number of columns in the scroller less two (two scroller 
columns are reserved for the prefix area). 


Default number of rows to roll scroller by. The default number of rows to roll scroller by for the Roll 
Scroller Up (QsnRollSclUp) and Roll Scroller Down (QsnRollSclDown) APIs. This value must be a 
positive integer value. If 0 is specified, the default is the number of rows in the scroller. 


Display control characters indication. Specifies whether or not scroller lines contain EBCDIC display 
control characters. If the data contains such control characters and this is not indicated, unexpected results 
can occur. (See EBCDIC Display Control Characters for details of the control characters supported and 


their interpretation.) The possible values are: 


O Scroller lines do not contain EBCDIC display control characters. This is the default. 


I Scroller lines contain EBCDIC display control characters. If 1 is specified, any data written to the 
session with a value below X'40' is converted to blank. 


Echo session input. Specifies whether lines entered at the session command line are to be echoed to the 
scroller. The possible values are: 


0 Do not echo session input lines to the scroller. 


I Echo session input lines to the scroller. This is the default. 


Input line attribute for a color display. The default value is X'24' for green underline attribute. If X'00' is 
specified, the default value is used. 


Input line attribute for a monochrome display. The default value is X'24' for underline attribute. If X'00' 
is specified, the default value is used. 


Input line prompt. The text string for the input line prompt. 


Left column of scroller. This position is relative to the left of the window which is column 1. The default 
is 1. 


Length of command key description line 1. This value must not exceed the maximum number of columns 
in the window. The default value is 0. No space is used in the session for this line. If the description line 
cannot be displayed completely within the window, it is truncated to fit. 


Length of command key description line 2. This value must not exceed the maximum number of columns 
in the window. The default value is 0. No space is used in the session for this line. If the description cannot 
be displayed completely in the window, it is truncated to fit. 


Length of input line prompt. This value must not exceed the maximum number of columns in the 
window. A value of 0 specifies that there is no prompt. The default value is -1 and corresponds to the 
default input line prompt ===. 


If the input line cannot be displayed completely within the window, it is truncated to fit. The input line will 
continue on the next window line. 


Number of columns in scroller. This value must be a positive integer no greater than the number of 
columns in the session window. If 0 is specified, the default is the number of columns remaining in the 


window from the left column of the scroller. This value includes the 2 bytes used for the prefix area to the 
left of the scroller input line. 


Number of rows for input line. The input line starts in the row specified by the formula: last window row 
less the number of rows required for input line less the number of rows required for the function key 
descriptions. The input line will start one column past the end of the input line prompt. If there is no input 
line prompt, then the input line starts one byte to the center of the leftmost usable column of the window. If 
this value is 0, then no input line is created. The default is 1. 


Number of rows in scroller. This value must be a positive integer no greater than the number of rows in 
the session window. If 0 is specified, the default is the number of rows remaining in the window from the 
top row of the scroller. 


Offset to command key description line 1. The offset from the beginning of the structure to the start of 
the command key description line 1. This field is ignored if the length of command key description line 1 
field specifies no command key description. The offset plus the length must be less than the session 
description length. 


Offset to command key description line 2. The offset from the beginning of the structure to the start of 
the command key description line 2. This field is ignored if the length of command key description line 2 
field specifies no command key description. The offset plus the length must be less than the session 
description length. 


Offset to input line prompt. The offset from the beginning of the structure to the start of the input line 
prompt. This field is ignored if the length of input line prompt field specifies no prompt or the default 
prompt. The offset plus the length must be less than the session description length. 


Reserved. This field must be set to X'00'. 


Scroller buffer increment. Specifies, in bytes, the amount to increment the scroller buffer size by when 
the buffer is full and the buffer-full action is to increment the buffer size. The default value is 2000 bytes. 


If the scroller buffer cannot be incremented because of insufficient resources, data at the beginning of the 
scroller will be removed to create space for the new data. 


Scroller buffer initial size. The initial buffer size, in number of bytes, that will be allocated for storing the 
session scroller lines. The default value is 2000 bytes. 


Scroller buffer maximum size. The maximum buffer size, in bytes, that will be allocated for storing the 
session scroller lines. The default value is 0, indicating no maximum size. 


Show command key descriptions. Whether or not the function key description lines are to be shown. The 
possible values are: 


O Do not show function key descriptions. 


I Show function key descriptions. This is the default. 


Show scroller characters. Whether or not characters written to the scroller in character mode are shown 
immediately on the screen. You can use the scroller line and character display options together to specify 
that groups of characters are not displayed immediately, but each complete line is. The possible values are: 


0 Do not show characters on the screen as they are written. Use the Display Scroller bottom 
(QsnDspSclB) API to display the scroller data on the screen. This is the default. 


I Show scroller characters on the screen as they are written. 


Show scroller lines. Whether or not lines written to the scroller are shown immediately on the screen. The 
possible values are: 


0 Do not show scroller lines on the screen as they are written. Use the Display Scroller bottom 
(QsnDspSclB) API to display the scroller lines on the screen. This is the default. 


I Show scroller lines on the screen as they are written. 


Top row of scroller. This position is relative to the top of the window, which is row |. The default is 1. 


Wrap indication. How to handle lines that do not fit within the session window. Possible values are: 


O Truncate lines that do not fit. The truncated portion of the line may be viewed by scrolling to the 
center. 


1 Wrap lines to the next line. This is the default. A value of 1 must be specified if the session contains 
DBCS data. 


Format of the Session User Extension Data 


| Offset 
| Dec Hex /|Type Field 


| 0 0 PTR(SPP) User data associated with the session 
| 16 10  |PTR(PP) Exit routine to call when the session is changed 
| 32 20 |PTR(PP) Exit routine to call when window is deleted 


48 30 =|PTR(PP) Exit routine to call when window coordinates 
are changed 


| 64 40  |PTR(PP) Exit routine to call when window is drawn 


80 50. |PTR(PP) Exit routine to call when this window made 
current 


Field Descriptions 


Exit routine to call when session changed. The exit routine to call when a session is changed using the 
Change Session (QsnChgSsn) API. 


Exit routine to call when window coordinates changed. The exit routine to call when the window 
coordinates are changed using the QsnMovWin, Move Window by User (QsnMovWinUsr), Resize 
Window ( QsnRszWin), or Resize Window by User (QsnRszWinUsr), APIs. 


Exit routine to call when window deleted. The exit routine to call when a window is deleted using the 
Delete Low-Level Environment (QsnDItEnv) API. 


Exit routine to call when window drawn. The exit routine to call when a window is drawn using the 
Display Window (QsnDspWin) API. 


Exit routine to call when window made current. The exit routine to call when this window is made 
current using the Set Current Window (QsnSetCurWin) API. 


User data associated with the session. This is a pointer to any data that the user wants to associate with 
this session. 


Session Exit Routines 


Exit routines are user-supplied functions with a defined interface. The routines are called from certain APIs 
and allow the programmer to attach additional function to those APIs. For instance, if fields have been set 
up in a window, a Change Coordinates exit routine could be supplied to move the fields if the window is 
moved. 


Change Session Exit Routine 


This exit routine, if specified on the user extension information, is called when the session is changed. The 
following parameter is passed to the exit routine: 


Parameter Passed to Exit Routine 


1 Session handle Input Binary(4) 


Change Session Exit Routine Parameter 


Session handle 
INPUT; BINARY(4) 


The session that was changed. 


Delete Session Exit Routine 


This exit routine, if specified on the user extension information, is called when the session is deleted. The 
following parameter is passed to the exit routine: 


Parameter Passed to Exit Routine 


1 Session handle Input Binary(4) 


Delete Session Exit Routine Parameter 


Session handle 
INPUT; BINARY(4) 


The session that was deleted. 


Change Session Coordinates Exit Routine 


This exit routine, if specified on the user extension information, is called when the move or resize APIs are 
called. It is called after the session has been successfully moved or resized, but before the session is drawn 
on the screen. For this reason, you should not use this exit routine to draw anything in the session. The draw 
exit routine will be called when the session is moved or resized. The following parameters are passed to the 
exit routine: 


Parameters Passed to Exit Routine 


Session handle Binary(4) 
Top border offset Binary(4) 


Left border offset Binary(4) 
Bottom border offset Binary(4) 
Center border offset Binary(4) 


Change Session Coordinates Exit Routine Parameters 


Session handle 
INPUT; BINARY(4) 


The Session for which the coordinates were changed. 
Top border offset 
INPUT; BINARY(4) 


The offset, in screen rows, from the previous top session border to the current top session border 
(after the session coordinates have been changed). It can be positive, negative, or zero, depending 
on how the top session border was changed. For example, if the top border was moved down two 
rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the top row was 
not changed, this value would be 0. 


Left border offset 
INPUT; BINARY(4) 


The offset, in screen columns, from the previous left session border to the current left session 
border (after the session coordinates have been changed). It can be positive, negative, or zero, 
depending on how the left session border was changed. For example, if the left border was moved 
two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value 


would be -4, and if the left column was not changed, this value would be 0. 
Bottom border offset 
INPUT; BINARY(4) 


The offset, in screen rows, from the previous bottom session border to the current bottom session 
border (after the session coordinates have been changed). It can be positive, negative, or zero, 
depending on how the bottom session border was changed. For example, if the border was moved 
down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the 
bottom row was not changed, this value would be 0. 


Center border offset 
INPUT; BINARY(4) 


The offset, in screen columns, from the previous center session border to the current center session 
border (after the session coordinates have been changed). It can be positive, negative, or zero, 
depending on how the center session border was changed. For example, if the center border was 
moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, this 
value would be -4; if the center column was not changed, this value would be 0. 


Exit Routine Error Handling 


If an exception occurs during the processing of an exit routine, the exception is ignored and processing 
continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an 
exit routine by adding an exception handler to the routine. 


Draw Session Exit Routine 


This exit routine, if specified on the user extension information, is called when the Display Window 
(QsnDspWin) API is called, before the session is drawn. Because the exit routine is called before the 
session is drawn, you should only write inside the session using the command buffer parameter. Direct 
operations should not be used for the exit routine. 


The following parameters are passed to the exit routine: 


Parameters Passed to Exit Routine 


1 Session handle Input Binary(4) 
2 Command buffer Input Binary(4) 


Draw Session Exit Routine Parameters 


Session handle 
INPUT; BINARY(4) 


The session to be drawn. 


Command buffer 
INPUT; BINARY(4) 
The command buffer used to store the commands that re-create the window contents. The contents 


of the command buffer are written to the screen along with the window border. This allows the 
window and its contents to be redrawn in a single I/O operation. 


Current Session Exit Routine 


This exit routine, if specified on the user extension information, is called when the session is made current 
through the Set Current Window (QsnSetCurWin) API. The following parameter is passed to the exit 
routine: 


Parameter Passed to Exit Routine 


1 Session handle Input Binary(4) 


Current Session Exit Routine Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that is made current. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA314 E Memory allocation error. 

CPFA318 E Error calling exit routine. 

CPFA327 E Low level environment description value incorrect. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 


CPFA3A1 E Window description value is incorrect. 
CPFA3AB E The value for &1 must be '0' or'1’. 


CPFA3D1 E Session description value is incorrect. 


Additional errors may be generated by this API. They are listed under the applicable API as follows: 


Error Category (API Page Reference 
Environment description (QsnCrtEnv) Error Messages 


Window description (QsnCrtWin) Error Messages 


For examples of Create Session APIs, see Create Session and Read Data--Example. 
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Display Scroller Bottom (QsnDspSclIB) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Display Scroller Bottom (QsnDspSclB) API positions the scroller at the last line in the scroller area. As 
many lines preceding the last line as can fit in the scroller area are displayed as well. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be manipulated. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3D6 E Session handle is incorrect. 
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Display Scroller top (QsnDspSclT) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Display Scroller top (QsnDspScIT) API positions the scroller at the first line in the scroller area. As 
many lines following the first line as can fit in the scroller area are displayed as well. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be manipulated. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3D6 E Session handle is incorrect. 
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Initialize Session Description (QsnInzSsnD) API 


Required Parameter Group: 


1 Session description Output Char(*) 
2 Length of session description Input Binary(4) 


Omissible Parameter: 


3. Error code Char(*) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Initialize Session Description (QsnInzSsnD) API initializes a session description with default values. 
Unless otherwise specified in the session description (see Format of the Session Description), pointer fields 
are set to the null pointer, numeric fields to 0, character flag fields to 0, and other character fields to blanks. 
For example, the default value for the wrap indication is 1, so this field will be set to 1. 


Authorities and Locks 


Exit Routine Authority 
*EXECUTE 


Required Parameter Group 


Session description 
OUTPUT; CHAR(*) 


The session description to be initialized. 
Length of session description 
INPUT; BINARY(4) 


The length of the session description parameter. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1D E Length specified in parameter &1 not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 
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Query If Scroller in Line Wrap Mode 
(QsnQrySclWrp) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Wrap indication Char(1) 
3. Error code Char(*) 


Returned Value: 


Wrap indication Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Query If Scroller in Line Wrap Mode (QsnQrySclWrp) API queries if line wrap mode is set on or off 
for the given session. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be queried. 


Omissible Parameter Group 


Wrap indication 
OUTPUT; CHAR(1) 


Whether line wrap mode is on or off. The possible values are: 


O Line wrap mode is off. 


7 Line wrap mode is on. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Wrap indication 
OUTPUT; BINARY(4) 


This API returns the value for the wrap indication parameter if the operation was successful, or -1 
otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA3D6 E Session handle is incorrect. 
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Retrieve Number of Columns to Shift Scroller 
(QsnRtvSclNumShf) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Shift amount Binary(4) 
3 Error code Char(**) 


Returned Value: 
Shift amount Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Number of Columns to Shift Scroller (QsnRtvSclNumShf) API returns the default number of 
columns to shift the scroller by for the Shift Scroller top (QsnShfSclL) and Shift Scroller center 
(QsnShfSclR) APIs. The default number of columns is specified on the session description. See Create a 


Session (QsnCrtSsn) API and Change Session (QsnChgSsn) API for details. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be queried. 


Omissible Parameter Group 


Shift amount 
OUTPUT; BINARY(4) 


The variable that contains the number of scroller columns to shift by when the QsnRtvSclNumShf 
API has completed. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Shift amount 
OUTPUT; BINARY(4) 


Returns the value for the shift amount parameter if the operation was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA3D6 E Session handle is incorrect. 
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Retrieve Number of Rows to Roll Scroller 
(QsnRtvSclINumRoll) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Roll amount Binary(4) 
3 Error code Char(**) 


Returned Value: 
Roll amount Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Number of Rows to Roll Scroller (QsnRtvSclINumRoll) API returns the default number of 
rows to roll the scroller by for the Roll Scroller Up (QsnRollSclUp) and Roll Scroller Down 
(QsnRollSclDown) APIs. The default number of rows is specified on the session description. See Create a 


Session (QsnCrtSsn) API and Change Session (QsnChgSsn) API for details. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be queried. 


Omissible Parameter Group 


Roll amount 
OUTPUT; BINARY(4) 
The variable that contains the number of scroller rows to roll by when the QsnRtvSclNumRoll API 
has completed. 
Error code 
1/O; CHAR(*) 
The structure in which to return error information. For the format of the structure, see Error Code 


Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Roll amount 
OUTPUT; BINARY(4) 


This API returns the value for the roll amount parameter if the operation was successful, or -1 
otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA3D6 E Session handle is incorrect. 
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Retrieve Session Data (QsnRtvSsnDta) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 User data pointer PTR(SPP) 
3. Error code Char(*) 


Returned Value: 


User data pointer PTR(SPP) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Session Data (QsnRtvSsnDta) API returns a pointer to the user data for the given session. The 
user data is the pointer specified on the session description and consists of user-specified data that is 
associated with the session. See Format of the Session Description for details. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session for which the user data should be returned. 


Omissible Parameter Group 


User data pointer 
OUTPUT; PTR(SPP) 


A pointer to the user data, as specified on the session description, for the given session. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


User data pointer 
OUTPUT; PTR(SPP) 


This API returns the value for the user data pointer parameter if the operation was successful, or the 
null pointer if an error occurs. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C1F E Pointer is not on a 16 byte boundary. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA3A4 E Specified window is not active. 

CPFA3D6 E Session handle is incorrect. 
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Retrieve Session Description (QsnRtvSsnD) 
API 


Required Parameter Group: 


1. Session handle Input Binary(4) 
2 Session description Output Char(*) 
3. Length of session description Input Binary(4) 


Omissible Parameter: 


4 Error code 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Session Description (QsnRtvSsnD) API retrieves a copy of the session description for the 
given session. The session description may be different from the session description used when the Create a 
Session (QsnCrtSsn) or the Change Session (QsnChgSsn) API is called. The following fields will have 
actual values replacing 0 (if used): 

Number of rows in scroller 

Number of columns in scroller 


Default number of rows to roll scroller by 


Default number of columns to shift scroller by 


Authorities and Locks 


None 


Required Parameter Group 


Session handle 
INPUT; BINARY(4) 


A handle for the session for which the session description should be returned. 
Session description 
OUTPUT; CHAR(*) 


The format of the data is shown in Format of the Session Description Returned. 


Length of session description 
INPUT; BINARY(4) 


The length of the session description parameter. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Format of the Session Description Returned 


| Offset 
| Dec Hex /|Type Field 


| 0 0 BINARY(4) Bytes returned 
| 4 4 BINARY(4) Bytes available 
| 8 8 CHAR(8) Reserved 


16 10 |CHAR(*) Session description. The format of the 
remaining data returned is shown in Format of 
the Session Description. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3C24 E Length of the receiver variable is not valid. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA3D6 E Session handle is incorrect. 
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Roll Scroller Down (QsnRollSciDown) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Roll amount Binary(4) 
3 Error code Char(**) 


Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Roll Scroller Down (QsnRollSclDown) API rolls the scroller down by the specified number of scroller 
rows. A scroller row is distinct from a scroller line in that a scroller line consists of multiple scroller rows if 
line wrapping is set on and the line exceeds the width of the scroller. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be rolled. 


Omissible Parameter Group 


Roll amount 
INPUT; BINARY(4) 


The number of scroller rows to roll the scroller by. If this parameter is omitted or set to 0, the 


default value is used. The default value can be queried using the Retrieve Number of Rows to Roll 
Scroller (QsnRtvSclNumRoll) API. If the roll amount would cause the scroller to roll past its top, 
then the top of the scroller will be displayed. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA333 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3D3 E 
CPFA3D6 E 
CPFA3D8 E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Parameter &1 not positive integer value. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Scroller not printed. 

Session handle is incorrect. 


Scroller display is not valid. 
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Roll Scroller Up (QsnRollSclUp) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Roll amount Binary(4) 
3 Error code Char(**) 


Returned Value: 
Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Roll Scroller Up (QsnRollSclUp) API rolls the scroller up by the specified number of scroller rows. A 
scroller row is distinct from a scroller line in that a scroller line consists of multiple scroller rows if line 
wrapping is set on and the line exceeds the width of the scroller. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be rolled. 


Omissible Parameter Group 


Roll amount 
INPUT; BINARY(4) 


The number of scroller rows to roll the scroller by. If this parameter is omitted or set to 0, the 


default value is used. The default value can be queried using the Retrieve Number of Rows to Roll 
Scroller (QsnRtvSclINumRoll) API. If the roll amount causes the scroller to roll past its bottom, 
then the bottom of the scroller is displayed. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA333 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3D3 E 
CPFA3D6 E 
CPFA3D8 E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Parameter &1 not positive integer value. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Scroller not printed. 

Session handle is incorrect. 


Scroller display is not valid. 
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Shift Scroller left (QsnShfSciL) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Shift amount Binary(4) 
3_ Error code Char(**) 


Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Shift Scroller left (QsnShfSclL) API shifts the scroller to the left by the specified number of scroller 
columns. If line wrap mode is on, shifting has no effect. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be shifted. 


Omissible Parameter Group 


Shift amount 
INPUT; BINARY(4) 


The number of scroller columns to shift the scroller by. If this parameter is omitted or set to 0, the 
default value is used. The default value can be queried using the Retrieve Number of Columns to 


Shift Scroller (QsnRtvSclNumShf) API. The scroller is shifted by the minimum of the shift amount 
and the number of scroller columns between the visible left column and the first column in the 


scroller. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA333 E 
CPFA31E E 
CPFA340 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3D6 E 
CPFA3D8 E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Parameter &1 not positive integer value. 
Required parameter &1 omitted. 

Operation not supported with double-byte data. 
Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Session handle is incorrect. 


Scroller display is not valid. 
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Shift Scroller Right (QsnShfSciR) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Shift amount Binary(4) 
3 Error code Char(**) 


Returned Value: 


Return code Binary(4) 


Service Program: QSNAPI 


Default Public Authority: *USE 


Threadsafe: No 


The Shift Scroller Right (QsnShfSclIR) API shifts the scroller to the right by the specified number of 
scroller columns. Any truncated data will become visible. If line wrap mode is on, shifting has no effect. 


Authorities and Locks 


None. 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be shifted. 


Omissible Parameter Group 


Shift amount 
INPUT; BINARY(4) 


The number of scroller columns to shift the scroller by. If this parameter is omitted or set to 0, the 


default value is used. The default value can be queried using the Retrieve Number of Columns to 
Shift Scroller (QsnRtvSclNumShf) API. The scroller is shifted by the minimum of the shift amount 
and the number of scroller columns between the visible center column and the last column 
(determined by the longest line currently visible) in the scroller. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error code 
parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Return code 


OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA333 E 
CPFA31E E 
CPFA340 E 
CPFA343 E 
CPFA344 E 
CPFA345 E 
CPFA3D6 E 
CPFA3D8 E 
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Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Parameter &1 not positive integer value. 
Required parameter &1 omitted. 

Operation not supported with double-byte data. 
Output operation not done. 

The file &2 in library &3 is not valid. 

The invite active flag is not valid. 

Session handle is incorrect. 


Scroller display is not valid. 
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Toggle Line Wrap/Truncate Mode 
(QsnTglSclWrp) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter Group: 


2 Wrap indication Char(1) 
3. Error code Char(*) 


Returned Value: 


Wrap indication Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Toggle Line Wrap/Truncate Mode (QsnTglSclWrp) API toggles the session between line wrap and 
truncation mode. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session to be queried. 


Omissible Parameter Group 


Wrap indication 
OUTPUT; CHAR(1) 


Indicates whether line wrap mode is on or off when the QsnTglSclWrp API has completed. The 
possible values are: 


O Line wrap mode is now off. Lines are truncated. 


7 Line wrap mode is now on. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Wrap indication 
OUTPUT; BINARY(4) 


This API returns the value for the wrap indication parameter if the operation was successful, or -1 
otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 
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Session I/O APIs 


For additional information, see: 


e Performance considerations 


e Example: Create Session and Read Data 


The session I/O APIs are: 


e Backspace on Scroller Line (QsnSclBS) sets the active position to the previous position in the 
current scroller line. 


e Goto Next Tab Position in Scroller Line (QsnSclTab) sets the active position to the next horizontal 
tab position. 


e Goto Start of Current Scroller Line (QsnScICR) sets the active position to the start of the current 
scroller line. 


e Goto Start of Next Scroller Line (QsnScINL) sets the active position to the start of the next scroller 
line. 


e Print Scroller Data (QsnPrtScl) prints the scroller data. 


e Read Data from Session (QsnReadSsnDta) reads the data from a session. 


e Retrieve Session Line to Input Line (QsnRtvSsnLin) retrieves the input line from the scroller. 


e Start New Scroller Line at Current Position (QsnScILF) sets the active position to the current 
position on the next scroller line. 


e Start New Scroller Page (QsnScIFF) starts a new scroller page. 


e Write Characters to Scroller (QsnWrtSclChr) writes characters to the scroller. 


e@ Write Line to Scroller (QsnWrtSclLin) writes a data line to the scroller. 
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Using Session I/O APIs 


Performance Considerations 


Specifying EBCDIC control-character options on the session description can incur overhead. Additional processing is 
required to handle these. Specifying the scroller line and character display as immediate can incur additional overhead. An 
output operation will occur for each line or group of characters written. If you need to write multiple lines to the scroller, 
you can achieve better performance by delaying line display until all the lines are written. Then you can use the Display 


Scroller Bottom (QsnDspSclB) API to display the data on the screen. 


Create Session and Read Data--Example 


The sample program in Figure | shows how to create and read data from a session. The resulting screen output is shown in 


Figure 2. 


Figure 1. Program for Creating a Session and Reading Data 


#include <stddef.h> 
#include <stdlib.h> 
#include <string.h> 
#include <stdio.h> 
#include "qsnapi.h" 


#define TRUE 1. 
#define FALS! 0 


Gl 


#define PF1l "PF4 - Move PF5 - Resize" 
#define PF2 "PF6 - Print" 


typedef struct { 
Qsn_Ssn_Desc_T sess_desc; 
char buffer[100]; 
} storage_t; 


int main (void) 

{ 
Qsn_Inp_Buf_T ibuf = 0; 
char *fld_dta; 


int i; 

char text[100]; 

storage_t storage; 

Qsn_Ssn_T sessionl; 

Qsn_Ssn_Desc_T *sess_desc = (Qsn_Ssn_Desc_T *) &storage; 

Qsn_Win_Desc_T win_desc; 

Q Bin4 win_desc_length = sizeof (win_desc) ; 

char *pfl = PF1; 

Q Bin4 pfl_len = sizeof(PF1) - 1; 

char *pf2 = PF2; 

Q Bin4 pf2_len = sizeof(PF2) - 1; 

Q Bin4 sess_desc_length = sizeof (Qsn_Ssn_Desc_T) 
pf2_len; 


/* initialize and set up session and window descriptions */ 
QsniInzSsnD( sess_desc, sess_desc_length, NULL); 


QsnInzWinD( &win_desc, win_desc_length, NULL); 


sess_desc-—>cmd_key_desc_line_1_offset 


sess_desc-—>cmd_key_desc_line_1_len 


= sizeof (Qsn_Ssn_Desc_T); 
pfl_len; 


+ pfl_len + 


memcpy ( storage.buffer, pfl, pfl_len ); 


sess_desc->cmd_key_desc_line_2_ offset = sizeof (Qsn_Ssn_Desc_T) 


pfl_len; 
sess_desc->cmd_key_desc_line_2_len = pf2_len; 
memcpy ( storage.buffer + pfl_len, pf2, pf2_len ); 


sess_desc->scl_line_dsp = '1'; 
sess_desc->scl_chr_dsp = '1'; 
sess_desc->num_input_line_rows = 2; 
sess_desc->wrap = '0'; 


QsnCrtSsn( sess_desc, sess_desc_length, NULL, 0, sd ae 
éwin_desc, win_desc_length, NULL, 0, 
&sessionl, NULL); 


if (ibuf == 0) 
ibuf = QsnCrtInpBuf (100, 50, 0, NULL, NULL); 
while ( TRUE ) { 
QsnReadSsnDta( sessionl, ibuf, NULL, NULL); 
/* check if any data read, then end if exit entered */ 


if ( (fld_dta=QsnRtvFldDta(ibuf, NULL, NULL)) != NULL) 
if (strncemp(fld_dta, "exit", 4) == 0) 
break; 


+ 


> this is line 2 


> more lines 


> more data 


> another line 


| : F4=Move F5=Resize 
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Backspace on Scroller Line (QsnScIBS) API 


Required Parameter: 

1 Session handle Binary(4) 
Omissible Parameter: 

2 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Backspace on Scroller Line (QsnSclIBS) API sets the active position to the previous position on the 
current scroller line. If the active position is at the start of the line, this operation has no effect. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 


signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 
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Go to Next Tab Position in Scroller Line 
(QsnSclTab) API 


Required Parameter: 

1 Session handle Binary(4) 
Omissible Parameter: 

2 Error code Char(*) 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Go to Next Tab Position in Scroller Line (QsnSclTab) API sets the active position to the next 
horizontal tab position. Each tab interval is eight positions beyond the previous one, starting at the leftmost 
column in the scroller. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 
signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA3D6 E Session handle is incorrect. 

CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
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Go to Start of Current Scroller Line (QsnScICR) 
API 


Required Parameter: 

1 Session handle Binary(4) 
Omissible Parameter: 

2 Error code Char(*) 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Go to Start of Current Scroller Line (QsnSclCR) API sets the active position to the start of the current 
scroller line. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 
signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 
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Go to Start of Next Scroller Line (QsnScINL) 
API 


Required Parameter: 

1 Session handle Binary(4) 
Omissible Parameter: 

2 Error code Char(*) 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Go to Start of Next Scroller Line (QsnScINL) API sets the active position to the start of the next 
scroller line. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 
signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 
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Print Scroller Data (QsnPrtScl) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter: 
2 Error code 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Print Scroller Data (QsnPrtScl) API prints the entire contents of the scroller data to the default printer 
file. No printer file is produced if the scroller is empty. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 

CPFA3D3 E Scroller not printed. 

CPFA3D6 E Session handle is incorrect. 
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Read Data from Session (QsnReadSsnDta) API 


Required Parameter Group: 


1 Session handle Binary(4) 
2 Input buffer handle Binary(4) 


Omissible Parameter Group: 


3 Number of bytes read Output Binary(4) 
4 Error code V/O Char(*) 


Returned Value: 


Number of bytes read Binary(4) 


Default Public Authority: *USE 
Service Program: QSNAPI 


Threadsafe: No 


The Read Data from Session (QsnReadSsnDta) API is used to read data from a session. A QsnReadInp 
operation is implicitly performed to read any field data. If the session has a DSM-defined input line, an 
implicit Clear Field Table (QsnClrFldTbl) operation is issued prior to redefining the session input line on 
each input operation. The data returned consists of only the data entered. That is, only the data from the 
cursor position within the field up to the last nonblank input character when an AID generating key is 
pressed is returned. If the session does not have a DSM-defined input line, data is read from any input fields 
defined on the screen, and all data, including blanks, is returned. In other respects, the processing of these 
user-defined input fields will be equivalent with the processing of the DSM-defined input line. 


If an AID key is pressed for which a corresponding function has been defined, this function will be called. 
Depending upon the return action specified, control would then return to the caller or another input 
operation will occur. See Command Key Action Routines for details. 


Authorities and Locks 


None 


Required Parameter Group 


Session handle 
INPUT; BINARY(4) 


A handle for the session from which to read input. The session being read from must be the current 
window. You can use the Set Current Window (QsnSetCurWin) API to change the current window. 


Input buffer handle 


INPUT; BINARY(4) 


A handle for the input buffer to receive the result of the input operations if a direct operation is 
specified. The input buffer must have been created with the Create Input Buffer (QsnCrtInpBuf) 
API. The format of the data returned is the same as that of the Read Input Fields (QsnReadInp) 


API. 


Omissible Parameter Group 


Number of bytes read 


OUTPUT; BINARY(4) 


The number of bytes of data read. On a successful read operation, this value is the same as that 
returned by the Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) API if passed the input 
buffer resulting from this operation. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Paramemter. If this parameter is omitted, diagnostic and escape messages are issued to the 


application. 


Returned Value 


Number of bytes read 


OUTPUT; BINARY(4) 


This API returns the value for the number of bytes read parameter if the operation was successful, 
-1 if there was a general failure, or -2 if the invite active flag is on in the associated environment 
and the read from invited device operation timed out. 


Error Messages 


Message ID 
CPF24B4 E 
CPF3CF1 E 
CPF3CF2 E 
CPFA31E E 
CPFA343 E 
CPFA344 E 
CPFA345 E 


Error Message Text 

Severe error while addressing parameter list. 
Error code parameter not valid. 

Error(s) occurred during running of &1 API. 
Required parameter &1 omitted. 

Output operation not done. 

The file &2 in library &3 is not valid. 


The invite active flag is not valid. 


CPFA3A4 E Specified window is not active. 
CPFA3D6 E Session handle is incorrect. 
CPFA3D9 E Error calling the command key action routine. 


For examples of Read Data from Session APIs, see Create Session and Read Data--Example. 
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Retrieve Session Line to Input Line 
(QsnRtvSsnLin) API 


Required Parameter: 
1 Session handle Binary(4) 
Omissible Parameter: 
2 Error code Char(*) 
Returned Value: 
Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Retrieve Session Line to Input Line (QsnRtvSsnLin) API retrieves the input line from the scroller that 
corresponds to the cursor position within the scroller. If the cursor is outside the scroller and the retrieve 
request directly follows another retrieve with no intervening I/O operations, then the line before the line 
previously retrieved is returned. Otherwise, the last input line is retrieved. If there is no input data, this API 
still completes successfully. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session for which to retrieve the input line. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA3A4 E Specified window is not active. 

CPFA3D6 E Session handle is incorrect. 
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Start New Scroller Line at Current Position 
(QsnScILF) API 


Required Parameter: 

1 Session handle Input Binary(4) 
Omissible Parameter: 
2 Error code Char(*) 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Start New Scroller Line at Current Position (QsnScILF) API sets the active position to the current 
position on the next scroller line. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 
signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session that the operation applies to. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 
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Start New Scroller Page (QsnScIFF) API 


Required Parameter: 

1 Session handle Binary(4) 
Omissible Parameter: 

2 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Start New Scroller Page (QsnSclIFF) API starts a new scroller page. Any data currently on the session 
is rolled off the top of the scroller, but can still be viewed by rolling the scroller up. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 


signaled. QsnWrtSclLin is the only DBCS-capable session output API. 


Authorities and Locks 


None 


Required Parameter 


Session handle 
INPUT; BINARY(4) 


A handle for the session for which to start the new page. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA31E E Required parameter &1 omitted. 

CPFA340 E Operation not supported with double-byte data. 
CPFA343 E Output operation not done. 

CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 

CPFA3D6 E Session handle is incorrect. 


API Introduced: V2R3 


Top | Dynamic Screen Manager APIs | APIs by category 


Write Characters to Scroller (QsnWrtSclChr) 
API 


Required Parameter Group: 


1 Session handle Binary(4) 
2 Data Char(*) 
3. Data length Binary(4) 


Omissible Parameter: 
4 Error code 
Returned Value: 


Return code Output Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Characters to Scroller (QsnWrtSclChr) API writes one or more characters to the scroller starting 
at the active position. The active position following this operation is one position past the last character 
written or that specified by a control character sequence if it appears at the end of the data. If the entire data 
string cannot fit in the scroller buffer, no portion of the string will be written. 


*Restrictions 


If the low-level environment description (see Format of the Low-Level Environment Description) for the 
session specifies DBCS support, a CPFA340 (Operation not supported with double-byte data.) will be 
signaled. QsnWrtSclLin is the only DBCS-capable session output API. * 


Authorities and Locks 


None 


Required Parameter Group 


Session handle 
INPUT; BINARY(4) 


A handle for the session to which the scroller characters are to be written. 
Data 
Input; CHAR(*) 
The characters to be written to the scroller. If the data does not fit within the width of the session 


window, it is wrapped across multiple lines or truncated, depending on the value of the wrap 
indication field on the session description. 


Data length 
Input; CHAR(*) 


The length of the data parameter. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA333 E Parameter &1 not positive integer value. 
CPFA31E E Required parameter &1 omitted. 


CPFA340 E Operation not supported with double-byte data. 


CPFA343 E Output operation not done. 


CPFA344 E The file &2 in library &3 is not valid. 
CPFA345 E The invite active flag is not valid. 
CPFA3D6 E Session handle is incorrect. 
CPFA3D7 E Data for scroller is too long. 
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Write Line to Scroller (QsnWrtSclLin) API 


Required Parameter Group: 


1 Session handle Binary(4) 
2 Line data Char(*) 
3 Line data length Binary(4) 


Omissible Parameter: 
4 Error code 
Returned Value: 


Return code Binary(4) 


Default Public Authority: *USE 


Service Program: QSNAPI 


Threadsafe: No 


The Write Line to Scroller (QsnWrtSclLin) API writes a line of data, such as an informational message, to 
the scroller. The data is written starting at the first position on the next scroller line. The active position 
after this operation is the start of the next scroller line following the row containing the last data character 
written, or specified by a control character sequence if one appears at the end of the data. If the entire line 
cannot fit in the scroller buffer, no portion of the data will be written. 


“Note: If the low-level environment description (see Format of the Low-Level Environment Description) 


for the session specifies DBCS support, the display control characters indication of the session description 
(see Format of the Session Description) is ignored. Any EBCDIC control characters in the line of data will 


be interpreted as shown in Table 9 - EBCDIC Display Control Characters in the Session Services APIs 
document. 


Authorities and Locks 


None 


Required Parameter Group 


Session handle 
INPUT; BINARY(4) 


A handle for the session to which the scroller line is to be written. 


Line data 
Input; CHAR(*) 
The data to be written to the scroller. If the line does not fit within the width of the session window, 
it is wrapped across multiple lines or truncated, depending on the value of the wrap indication field 


on the session description. 


Note: The first 2 bytes of the scroller are reserved for the prefix area to the left of the scroller line. 
Line data length 
Input; CHAR(*) 


The length of the line data parameter. 


Note: The first 2 bytes of the scroller are reserved for the prefix area to the left of the scroller line. 


Omissible Parameter 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the 
application. 


Returned Value 


Return code 
OUTPUT; BINARY(4) 


A return code indicating the result of the operation. The value returned will be 0 if the operation 
was successful, or -1 otherwise. 


Error Messages 


Message ID Error Message Text 

CPD0024 E No matching shift-in character for shift-out character. 
CPF24B4 E Severe error while addressing parameter list. 
CPF3CF1 E Error code parameter not valid. 

CPF3CF2 E Error(s) occurred during running of &1 API. 
CPFA333 E Parameter &1 not positive integer value. 

CPFA31E E Required parameter &1 omitted. 

CPFA343 E Output operation not done. 


CPFA344 E The file &2 in library &3 is not valid. 


CPFA345 E 
CPFA3D6 E 
CPFA3D7 E 
CPG3264 D 
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The invite active flag is not valid. 
Session handle is incorrect. 
Data for scroller is too long. 


DBCS character string does not have even length. 
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